PR Health Check

<!-- markdownlint-disable-file MD013 -->

Standardized patterns for validating PR health, merge-readiness, and determining if a PR can proceed through its workflow.

Purpose

Provides a single source of truth for PR status validation. All commands that need to verify PR readiness should use these patterns instead of duplicating health check logic.

Merge-Readiness Criteria

A PR is ready to merge when ALL of the following are true:

1. State: OPEN (not draft, closed, or merged)
2. Mergeable: MERGEABLE (no conflicts)
3. Status Checks: ALL must be SUCCESS (no failures, no pending)
4. Reviews: All required reviews must be APPROVED
5. Conversations: ALL review threads must be isResolved: true (use the pr-thread-resolution-enforcement skill)

Quick Health Check Query

Get comprehensive PR status:

gh pr view <PR_NUMBER> --json state,mergeable,statusCheckRollup,reviews,reviewDecision

Interpretation:

Field	Values	Meaning
state	OPEN, CLOSED, MERGED	Current state; must be OPEN
mergeable	MERGEABLE, CONFLICTING, UNKNOWN	Merge conflict status; must be MERGEABLE
statusCheckRollup	Array with status and conclusion	CI status; all must be SUCCESS
reviewDecision	APPROVED, CHANGES_REQUESTED, REVIEW_REQUIRED, null	Review status

Detailed Health Check Pattern

For comprehensive validation before merge attempts:

# Get full PR details
gh pr view <PR_NUMBER> --json state,mergeable,statusCheckRollup,reviews,reviewDecision,comments

# Verify each criterion:
# 1. State check: output should show "state": "OPEN"
# 2. Mergeable: output should show "mergeable": "MERGEABLE"
# 3. Status rollup: all items should have "conclusion": "SUCCESS"
# 4. Reviews: should show "reviewDecision": "APPROVED"
# 5. Conversations: use PR Thread Resolution Enforcement Skill verification query

Status Check Rollup Understanding

The statusCheckRollup field contains an array of check results:

{
  "state": "SUCCESS|FAILURE|PENDING",
  "contexts": [
    {"context": "Check Name", "state": "SUCCESS|FAILURE|PENDING"}
  ]
}

Interpretation:

• state: SUCCESS - All checks passed
• state: FAILURE - One or more checks failed
• state: PENDING - One or more checks still running

Actions:

• SUCCESS: Proceed if other criteria met
• FAILURE: Must fix before merge (see /finalize-pr command)
• PENDING: Must wait for checks to complete (use gh pr checks <PR_NUMBER> --watch)

PR Filtering Logic

Identify Healthy PRs

Use this logic to filter PRs that are merge-ready:

# List all open PRs
gh pr list --state open --json number,title,state,mergeable,statusCheckRollup,reviewDecision

# Filter for healthy PRs:
# - state == OPEN
# - mergeable == MERGEABLE
# - statusCheckRollup.state == SUCCESS
# - reviewDecision == APPROVED (for repos requiring reviews)

Identify PRs Needing Attention

Use this logic to find PRs with issues:

# List all PRs with issues
gh pr list --state open --json number,title,state,mergeable,statusCheckRollup

# Filter for unhealthy PRs:
# - state != OPEN (unusual, but check)
# - mergeable == CONFLICTING or UNKNOWN
# - statusCheckRollup.state != SUCCESS
# - Reviews not approved

Common Health Check Scenarios

Scenario 1: PR Ready to Merge

• state: OPEN ✓
• mergeable: MERGEABLE ✓
• statusCheckRollup.state: SUCCESS ✓
• reviewDecision: APPROVED ✓
• Action: Proceed with merge

Scenario 2: PR Has Merge Conflict

• mergeable: CONFLICTING ✗
• Action: Run /sync-main or manually resolve conflict

Scenario 3: CI Checks Failing

• statusCheckRollup.state: FAILURE ✗
• Action: Run /finalize-pr to diagnose and fix

Scenario 4: Checks Still Running

• statusCheckRollup.state: PENDING ⏳
• Action: Wait using gh pr checks <PR_NUMBER> --watch

Scenario 5: Missing Approvals

• reviewDecision: CHANGES_REQUESTED or REVIEW_REQUIRED ✗
• Action: Address feedback using /resolve-pr-threads

Commands Using This Skill

• /finalize-pr - Phase 2.1 (PR Health Check) and CI diagnosis for a single PR
• /finalize-prs - To filter which PRs need fixing and verify PRs are healthy before merge
• Any workflow needing PR status validation

Related Resources

• github-graphql skill - Detailed GraphQL queries for PR fields
• pr-thread-resolution-enforcement skill - Review conversation validation

Integration Points

With /finalize-pr

In /finalize-pr Phase 2.1, use this skill to determine next action:

# Get health status
gh pr view <PR_NUMBER> --json state,mergeable,statusCheckRollup,reviews,reviewDecision

# Determine action:
if mergeable != MERGEABLE: → /sync-main (conflict resolution)
if statusCheckRollup != SUCCESS: → /finalize-pr (CI fixes)
if reviewDecision != APPROVED: → /resolve-pr-threads (review feedback)
if all healthy: → Proceed to Phase 3

With /finalize-prs

Use PR health check to prioritize which PRs to fix:

# Get all PRs with failing checks
gh pr list --state open --json number,statusCheckRollup

# Filter where statusCheckRollup.state == FAILURE
# These PRs are candidates for /finalize-pr

Troubleshooting

Issue: statusCheckRollup returns null

Cause: PR checks haven't started yet

Solution: Wait a few seconds and retry, or use gh pr checks <PR_NUMBER>

Issue: mergeable returns UNKNOWN

Cause: GitHub is still calculating merge status

Solution: Wait 10-30 seconds and retry

Issue: Check shows SUCCESS but merge fails

Cause: Different checks ran since last query (rare race condition)

Solution: Re-run health check immediately before merge

Best Practices

1. Always check before merge - Use full health check even if PR "looks ready"
2. Interpret reviewDecision carefully - May differ from individual review states
3. Monitor pending checks - Use --watch flag to block until complete
4. Fix conflicts early - CONFLICTING status blocks everything else
5. Respect required reviews - Some repos require explicit approvals
6. Use skill queries verbatim - Exact same query each time ensures consistency