Pr Readiness

PR Readiness Check Skill

Verify that a Pull Request is truly ready to merge — not just that CI is green.

When to Use

• Before recommending any PR for merge
• When asked to "review PR", "check PR", "fix PR", or "babysit PR"
• When analyzing open PRs for a health report
• When asked to "fix CI" on open PRs
• After pushing conflict resolution or branch updates

Critical Rule

NEVER recommend merge based solely on CI status. You MUST also check:

1. mergeable field (conflicts?)
2. mergeStateStatus field (behind? blocked? dirty?)
3. All required checks passed (not just non-required ones)
4. No stale CANCELLED checks that should have run
5. All PR comments and reviews (human + bots) — actionable feedback addressed or explicitly waived with reason

Hard Blockers (NEVER BYPASS)

These rules have NO exceptions. Do not use --admin, --force, or any bypass mechanism:

1. NEVER merge when mergeStateStatus is UNSTABLE — Wait for all checks to complete.
2. NEVER merge when checks are pending — Wait for ALL checks to reach a terminal state.
3. NEVER use gh pr merge --admin to bypass branch protection — Fix the code, don't bypass the gate.
4. NEVER merge a PR you haven't personally verified — Run the full check and confirm ALL conditions.
5. NEVER skip loading this skill — Load this skill before any merge recommendation.
6. NEVER ignore PR comments — Fetch inline reviews, review bodies, and issue comments; address actionable feedback before declaring ready.

Full Procedure

1. Query All PR State

# Single PR (preferred when number known)
gh pr view {n} --json number,title,url,mergeable,mergeStateStatus,statusCheckRollup,headRefName,baseRefName,headRefOid,reviews,comments

# All open PRs
gh pr list --state open --json number,title,mergeable,mergeStateStatus,statusCheckRollup,headRefName,baseRefName

Also use the helper script:

./scripts/check-pr-readiness.sh [PR_NUMBER]
./scripts/check-pr-readiness.sh --fix [PR_NUMBER]   # also update BEHIND branches

2. Interpret mergeStateStatus

3. Interpret CI Check Conclusions

4. Fetch ALL PR Comments (MANDATORY)

Do not stop at CI. Always pull every feedback channel:

OWNER_REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
N={pr_number}

# A) Inline review comments (file/line threads)
gh api "repos/${OWNER_REPO}/pulls/${N}/comments" --paginate > /tmp/pr${N}_inline.json

# B) Submitted reviews (APPROVED / CHANGES_REQUESTED / COMMENTED + body)
gh api "repos/${OWNER_REPO}/pulls/${N}/reviews" --paginate > /tmp/pr${N}_reviews.json

# C) Issue-style conversation comments (Codecov, Codacy, humans, bots)
gh api "repos/${OWNER_REPO}/issues/${N}/comments" --paginate > /tmp/pr${N}_issue.json

# Optional: conversation via gh
gh pr view ${N} --comments

Parse and classify every item:

5. Address Feedback (not just acknowledge)

For each actionable comment:

1. Understand — reproduce or map to code
2. Fix or waive — implement the change, or document why not (with evidence)
3. Verify — tests / clippy / targeted nextest as appropriate
4. Close the loop — push commits; reply on the PR thread summarizing what was done
5. Re-check readiness — CI + merge state + no new unresolved threads

Common bot feedback patterns

Waiving feedback (rare)

Only waive when:

• Comment is outdated (code already changed) — reply with commit SHA
• Comment is incorrect — reply with counter-evidence
• Purely informational bot post (e.g. benchmark dump with no regression)

Never waive CHANGES_REQUESTED without either implementing the change or getting explicit re-approval.

6. Fix Procedures (CI / merge state)

Branch Behind Main (BEHIND)

# Preferred: typed CLI (R-H4)
gh pr update-branch {n}
# Fallback if needed:
# gh api repos/{owner}/{repo}/pulls/{n}/update-branch -X PUT -f update_method=merge

Merge Conflicts (DIRTY / CONFLICTING)

gh pr checkout {n}
git merge origin/main
# resolve <<<<<<< markers
git add <files> && git commit --no-edit && git push

Cancelled CI

gh run rerun {run_id}
# or: git commit --allow-empty -m "chore: re-trigger CI" && git push

Failed CI

gh run view {run_id} --log-failed
# Fix via .agents/skills/ci-fix/SKILL.md

7. Verification After Fix

gh pr view {n} --json mergeable,mergeStateStatus,statusCheckRollup
# Re-fetch comments to ensure no new open threads
gh api "repos/${OWNER_REPO}/pulls/${n}/comments" --paginate
gh api "repos/${OWNER_REPO}/issues/${n}/comments" --paginate

A PR is ready to merge ONLY when ALL of:

• mergeable = MERGEABLE
• mergeStateStatus = CLEAN
• All required statusCheckRollup entries = SUCCESS or SKIPPED
• No stale CANCELLED checks that should have run
• All actionable PR comments addressed (fixed + pushed, or waived with evidence on the thread)
• No open CHANGES_REQUESTED review without follow-up approval

Common Mistakes

❌ Wrong: Check only CI status

"All checks pass → ready to merge"

✅ Correct: CI + merge state + comments

"CI green, mergeStateStatus=CLEAN, all review/bot feedback addressed → ready to merge"

❌ Wrong: Ignore Codecov / Codacy conversation comments

"No human reviews → nothing to address"

✅ Correct: Bots count

"Codecov reports 54 missing lines on config_template.rs → add tests, push, reply on PR"

❌ Wrong: "Acknowledged" without code change

"Thanks for the review" (no fix, no test, no waiver evidence)

✅ Correct: Fix or evidence-based waiver

Implement + test + push; reply with what changed and commit SHA

❌ Wrong: Recommend merge while checks are pending

✅ Correct: Wait for ALL checks terminal

❌ Wrong: Use gh pr merge --admin

✅ Correct: Fix the underlying issue

Output Format

When reporting PR readiness, always include:

## PR #{number}: {title}
- **URL**: {url}
- **Merge State**: {mergeStateStatus} ({mergeable})
- **CI Status**: {pass} pass, {fail} fail, {pending} pending, {cancelled} cancelled
- **Codacy**: {status}
- **Comments**:
  - Inline review threads: {n} ({open} open / {resolved} resolved)
  - Reviews: {APPROVED / CHANGES_REQUESTED / COMMENTED counts}
  - Issue comments: {n} (list bots + humans with actionable summary)
  - Actionable remaining: {list or "none"}
- **Feedback addressed this session**: {what was fixed / waived}
- **Verdict**: READY TO MERGE | NEEDS FIX: {reason} | WAITING ON CI
- **Action**: {specific next step, or "None — merge when ready"}

Related

• Comments reference — Fetch/classify/close-loop templates
• .agents/skills/ci-fix/SKILL.md — CI failure diagnosis and repair
• .agents/skills/ci-poll/SKILL.md — Wait for CI with backoff
• .agents/skills/github-workflows/SKILL.md — Workflow patterns
• .agents/skills/code-quality/SKILL.md — fmt/clippy/coverage gates
• AGENTS.md → "PR Health Check" section — Quick reference table
• ./scripts/check-pr-readiness.sh — Automated merge/CI/comment gates