pr-health-check
Use when checking if PR is ready to merge. Validates merge-readiness and PR status patterns.
When & Why to Use This Skill
The pr-health-check skill provides a standardized framework for validating GitHub Pull Request readiness. It automates the verification of merge status, CI/CD success, review approvals, and conversation resolutions, ensuring that only fully compliant code is merged into the codebase. By centralizing PR health logic, it reduces manual oversight and prevents broken builds in the development lifecycle.
Use Cases
- Pre-merge Validation: Automatically verify if a PR is ready to merge by checking state, mergeability, and CI status in a single query to prevent integration errors.
- CI/CD Troubleshooting: Identify and diagnose failing or pending status checks to prioritize fixes and streamline the path to successful deployment.
- Review Workflow Enforcement: Ensure all required approvals are obtained and all review threads are resolved before proceeding with the merge.
- Conflict Management: Proactively detect merge conflicts with the main branch and trigger synchronization workflows to maintain PR health.
| name | pr-health-check |
|---|---|
| description | Use when checking if PR is ready to merge. Validates merge-readiness and PR status patterns. |
| version | "1.0.0" |
| author | "JacobPEvans" |
PR Health Check
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:
- State:
OPEN(not draft, closed, or merged) - Mergeable:
MERGEABLE(no conflicts) - Status Checks: ALL must be
SUCCESS(no failures, no pending) - Reviews: All required reviews must be
APPROVED - 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 passedstate: FAILURE- One or more checks failedstate: PENDING- One or more checks still running
Actions:
- SUCCESS: Proceed if other criteria met
- FAILURE: Must fix before merge (see
/fix-pr-cicommand) - 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-mainor manually resolve conflict
Scenario 3: CI Checks Failing
statusCheckRollup.state: FAILURE ✗- Action: Run
/fix-pr-cito 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-review-thread
Commands Using This Skill
/manage-pr- Phase 2.1 (PR Health Check)/fix-pr-ci- To filter which PRs need fixing/ready-player-one- To 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 Manage PR
In /manage-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: → /fix-pr-ci (CI fixes)
if reviewDecision != APPROVED: → /resolve-pr-review-thread (review feedback)
if all healthy: → Proceed to Phase 3
With Fix PR CI
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 /fix-pr-ci
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
- Always check before merge - Use full health check even if PR "looks ready"
- Interpret reviewDecision carefully - May differ from individual review states
- Monitor pending checks - Use
--watchflag to block until complete - Fix conflicts early - CONFLICTING status blocks everything else
- Respect required reviews - Some repos require explicit approvals
- Use skill queries verbatim - Exact same query each time ensures consistency