paperclipai/prcheckloop

PRCheckloop

Get a GitHub PR to a fully green check state, or exit with a concrete blocker.

Scope

• GitHub PRs only. If the repo is GitLab, stop and use check-pr.
• Focus on checks for the latest PR head SHA, not old commits.
• Focus on CI/status checks, not review comments or PR template cleanup.
• If the user also wants review-comment cleanup, pair this with check-pr.

Inputs

• PR number (optional): If not provided, detect the PR for the current branch.
• Max iterations: default 5.

Workflow

1. Identify the PR

If no PR number is provided, detect it from the current branch:

gh pr view --json number,headRefName,headRefOid,url,isDraft

If needed, switch to the PR branch before making changes.

Stop early if:

• gh is not authenticated
• there is no PR for the branch
• the repo is not hosted on GitHub

2. Track the latest head SHA

Always work against the current PR head SHA:

PR_JSON=$(gh pr view "$PR_NUMBER" --json number,headRefName,headRefOid,url)
HEAD_SHA=$(echo "$PR_JSON" | jq -r .headRefOid)
PR_URL=$(echo "$PR_JSON" | jq -r .url)

Ignore failing checks from older SHAs. After every push, refresh HEAD_SHA and restart the inspection loop.

3. Inventory checks for that SHA

Fetch both GitHub check runs and legacy commit status contexts:

gh api "repos/{owner}/{repo}/commits/$HEAD_SHA/check-runs?per_page=100"
gh api "repos/{owner}/{repo}/commits/$HEAD_SHA/status"

For a compact PR-level view, this GraphQL payload is useful:

gh api graphql -f query='
query($owner:String!, $repo:String!, $pr:Int!) {
  repository(owner:$owner, name:$repo) {
    pullRequest(number:$pr) {
      headRefOid
      url
      statusCheckRollup {
        contexts(first:100) {
          nodes {
            __typename
            ... on CheckRun { name status conclusion detailsUrl workflowName }
            ... on StatusContext { context state targetUrl description }
          }
        }
      }
    }
  }
}' -F owner=OWNER -F repo=REPO -F pr="$PR_NUMBER"

4. Wait for checks to actually run

After a new push, checks can take a moment to appear. Poll every 15-30 seconds until one of these is true:

• checks have appeared and every item is in a terminal state
• checks have appeared and at least one failed
• no checks appear after a reasonable wait, usually 2 minutes

Treat these as terminal success states:

• check runs: SUCCESS, NEUTRAL, SKIPPED
• status contexts: SUCCESS

Treat these as pending:

• check runs: QUEUED, PENDING, WAITING, REQUESTED, IN_PROGRESS
• status contexts: PENDING

Treat these as failures:

• check runs: FAILURE, TIMED_OUT, CANCELLED, ACTION_REQUIRED, STARTUP_FAILURE, STALE
• status contexts: FAILURE, ERROR

If no checks appear for the latest SHA, inspect .github/workflows/, workflow path filters, and branch protection expectations. If the missing check cannot be caused or fixed from the repo, escalate.

5. Investigate failing checks

For GitHub Actions failures, inspect runs and failed logs for the current SHA:

gh run list --commit "$HEAD_SHA" --json databaseId,workflowName,status,conclusion,url,headSha
gh run view <RUN_ID> --json databaseId,name,workflowName,status,conclusion,jobs,url,headSha
gh run view <RUN_ID> --log-failed

For each failing check, classify it:

| Failure type | Action | |---|---| | Code/test regression | Reproduce locally, fix, and verify | | Lint/type/build mismatch | Run the matching local command from the workflow and fix it | | Flake or transient infra issue | Rerun once if evidence supports flakiness | | External service/status app failure | Escalate with the details URL and owner guess | | Missing secret/permission/branch protection issue | Escalate immediately |

Only rerun a failed job once without code changes. Do not loop on reruns.

6. Fix actionable failures

If the failure is actionable from the checked-out code:

1. Read the workflow or failing command to identify the real gate.
2. Reproduce locally where reasonable.
3. Make the smallest correct fix.
4. Run focused verification first, then broader verification if needed.
5. Commit in a logical commit.
6. Push before re-checking the PR.

Do not stop at a local fix. The loop is only complete when the remote PR checks for the new head SHA are green.

7. Push and repeat

After each fix:

git push
sleep 5

Then refresh the PR metadata, get the new HEAD_SHA, and restart from Step 3.

Exit the loop only when:

• all checks for the latest head SHA are green, or
• a blocker remains after reasonable repair effort, or
• the max iteration count is reached

8. Escalate blockers precisely

If you cannot get the PR green, report:

• PR URL
• latest head SHA
• exact failing or missing check names
• details URLs
• what you already tried
• why it is blocked
• who should likely unblock it
• the next concrete action

Good blocker examples:

• external status app outage
• missing GitHub secret or permission
• required check name mismatch in branch protection
• persistent flake after one rerun
• failure needs credentials or infrastructure access you do not have

Output

When the skill completes, report:

• PR URL and branch
• final head SHA
• green/pending/failing check summary
• fixes made and verification run
• whether changes were pushed
• blocker summary if not fully green

Notes

• This skill is intentionally narrower than check-pr: it is a repair loop for PR checks.
• This skill complements greploop: Greptile can be perfect while CI is still red.