GH PR Fix Once

Goal

Do one full cleanup pass on an open GitHub pull request:

1. inspect failing or pending checks and unresolved review threads
2. address all currently known actionable issues
3. run applicable tests, lint, and build
4. commit and push the fixes
5. resolve only the threads actually addressed

Stop after that one pass. Do not sleep, poll, or keep looping for newly appearing issues.

When to use

Use this skill when the user asks to:

• address the current PR's known issues
• fix failing CI and unresolved review threads on a PR once
• do a one-off PR cleanup pass
• clear the current review and CI backlog without babysitting the PR afterward

Preconditions

• gh is installed and authenticated for the target repository
• the current branch already has an open PR, or the user provides a PR number or URL
• the agent has push access to the branch
• the repo can run the relevant local test/build commands

If authentication fails, stop and ask the user to run gh auth login.

Inputs

• cwd: repository root; default . if obvious
• pr: optional PR number or URL; default to the PR for the current branch

Quick start

Run the helper from the repo root:

uv run skills/gh-pr-fix-once/scripts/pr_health.py --cwd .

Useful variants:

uv run skills/gh-pr-fix-once/scripts/pr_health.py --cwd . --json
uv run skills/gh-pr-fix-once/scripts/pr_health.py --cwd . --pr 123
uv run skills/gh-pr-fix-once/scripts/pr_health.py --cwd . --resolve-thread <thread-id>

Workflow

1. Verify repo and PR context

• Run gh auth status.
• Resolve the active PR with gh pr view if the user did not provide one.
• If no open PR exists for the branch, stop and report that blocker.

2. Inspect current PR health

• Run the helper script to collect:
  • failing checks
  • pending checks
  • unresolved review threads
  • current review decision
• If the helper is unavailable, fall back to:
  • gh pr checks <pr> --json bucket,name,state,link,workflow
  • gh api graphql for reviewThreads

3. Build the actionable issue list for this pass

• Include every unresolved review thread that has a concrete requested change.
• Include every failing CI job.
• Include pending checks only when they reveal an already-known local validation gap or missing rerun trigger.
• Treat ambiguous or policy-level reviewer comments as blockers that require user input rather than guessing.

4. Implement fixes for all currently known actionable issues

• Inspect the referenced files, failing job logs, and affected code paths.
• Prefer the smallest set of coherent changes that clears the current issue list.
• If multiple issues share the same root cause, fix them together.
• If an item cannot be responsibly addressed without clarification, stop and report it as a blocker instead of silently skipping it.

5. Run validation before commit and push

• Run all applicable local validation for the changes you made:
  • targeted tests for the changed area
  • broader test suites when the failure or touched area warrants it
  • lint
  • build
• If lint or build is not relevant for the repo, state that explicitly before committing.
• Do not commit until the applicable validation for this pass has succeeded.

6. Commit and push

• Create a focused commit covering the issues addressed in this pass.
• Push the branch.
• Keep the commit scoped to the issues you actually handled.

7. Resolve addressed review threads

• Resolve only the threads actually addressed by the pushed change.
• Use the helper script with --resolve-thread, or the direct mutation:

gh api graphql \
  -f query='mutation($threadId:ID!) { resolveReviewThread(input:{threadId:$threadId}) { thread { id isResolved } } }' \
  -F threadId='<thread-id>'

• If a thread needs explanation rather than code, add the explanation first and only then resolve it when appropriate.

8. Report the one-pass outcome

• Summarize:
  • what was fixed
  • what validation ran
  • which threads were resolved
  • what still remains, if anything
• Stop after this report. Do not wait and poll again unless the user explicitly asks.

Helper script

Use scripts/pr_health.py to summarize PR status and resolve review-thread IDs.

What it reports:

• PR number and URL
• review decision
• failing and pending checks
• unresolved review threads with path, line, URL, author, and a short body excerpt
• whether the PR is currently clean

Exit codes:

• 0: clean PR
• 1: PR still has failing or pending checks or unresolved review threads
• 2: command or auth failure

Guardrails

• Do not resolve a review thread before the fix is pushed or the reply is posted.
• Do not guess at CI failures; read the failing job or log details first.
• Do not skip applicable tests, lint, or build before committing and pushing.
• Do not rewrite or force-push shared branches unless the user explicitly asks.
• Stop and ask the user when a comment implies a product decision, architectural disagreement, or conflicting reviewer guidance.