/fix-pr

name: fix-pr
description: Resolve the findings on an existing pull request - review comments, CI failures, and self-review findings - driving each to a decision (fix / defer to a tracked issue / discard), re-verifying the gates, replying to each reviewer, and watching for late feedback. The counterpart to pr-review that closes the loop.

Fix PR

Drive a PR's feedback to done: run a review, triage **every** item to a decision, fix what deserves fixing, file what deserves doing later, discard what deserves nothing, answer every reviewer, and re-check after pushing in case late feedback (bots, CI) arrives. The bar for correctness is high; the bar for new machinery is low — fix the defect, don't redesign around it.

0. Confirm the PR exists and is open (before anything else)

**Resolve the PR from the current branch — never trust a PR number carried over from earlier in the session** (it may be stale; acting on the wrong one, or claiming you did, is a false report). Run `gh pr view --json number,state,url,headRefName` (no argument = the current branch's PR), or `gh pr view <pr> --json number,state,url` when the user named one, and read `state`:

• **OPEN** → proceed.
• **CLOSED / MERGED** → **stop. Do not push commits, comment, resolve threads, or "post" anything to it** — a closed or merged PR won't take the work. Tell the user the PR is closed/merged and offer the real options: reopen it (if that's the intent), open a fresh PR from the current branch (`create-pr`), or point you at the correct open PR. Never claim you posted changes to it.
• **No PR for the branch** → there's nothing to fix; that's `create-pr`, not `fix-pr`.

For **bitbucket**/**gitlab**, do the equivalent state check (`/pullrequests/{id}` → `state`; `glab mr view <id>`). Never report having pushed to, commented on, or updated a PR you didn't first confirm is open.

1. Establish the PR intent (the scope ruler)

Write one or two sentences: **what this PR is for, and what it deliberately does not change** — derived from the title, body, linked issue, and the diff. Every scope call below is measured against it. If the intent is genuinely ambiguous, ask the author before triaging.

2. Gather the findings

Collect from every surface, deduplicated. Commands below are for `github` (`prHost` in `.claude/dev-kit.json`); for **bitbucket** use the REST API (`/pullrequests/{id}` comments, `/statuses`), for **gitlab** `glab mr view/checks`.

1. **CI failures**: `gh pr checks <pr>` — read the failing job logs, not just the status. 2. **Review feedback**: unresolved inline threads, review summary bodies, and PR conversation comments — bots included (`gh pr view <pr> --comments`, `gh api` for threads). Keep outdated threads: the code moved, the concern may not have. 3. **Self-review findings** handed over by the caller (the `pr-review` pass).

3. Build the ledger

One row per **distinct claim**, merging duplicates across sources (if the review pass and a human flagged the same defect, that's one row citing both — and the human's thread still gets a reply):

| id | source | file:line | claim | category | verdict |

Assign exactly one verdict per row — nothing stays undecided:

• **`FIX_NOW`** — fix it in this PR.
• **`DEFER_TO_ISSUE`** — real value, wrong moment → a tracked issue.
• **`DISCARD`** — not worth anyone's time; no fix, no issue.

**Never `DISCARD`** (from `instructions/secure-coding.md` + `instructions/testing-standards.md`): security/data-exposure, serious performance regressions, duplication this PR introduces, and missing test coverage for behavior it changes (when the project has tests). Only defer one of these when the fix is genuinely a separate project — and say so, treating the PR as blocked on the author's call, not quietly filing an issue.

Show the classified ledger before touching code — the cheapest moment to correct a bad call.

4. Ask about scope conflicts

Batch every fix that would push past the PR's intent into **one** round of questions (AskUserQuestion) with your recommendation. Don't widen scope silently.

5. Fix

Smallest correct change per `FIX_NOW`, following the repo's conventions and the kit instructions. Add/update the tests that prove each fix (a test that fails without it); keep touched files at the project's coverage bar (adaptive — see `testing-standards.md`). One commit per coherent group; push to the PR branch. No opportunistic refactors, no force-push/amend/rebase of remote commits.

6. Answer every reviewer (consent-first)

Reply to each human/bot comment with the decision taken, then resolve the thread. **Show the exact replies and get confirmation before posting to GitHub** (in `--auto-approve` pipeline runs, post them and flag prominently in the report). Never resolve someone else's thread without a reply. A finding you believe is wrong gets a reasoned reply, not silence.

7. File deferred work

For each `DEFER_TO_ISSUE`, confirm the batch with the user, then create a tracked issue **via the configured tracker** (the `issue-*` adapters / `.claude/dev-kit.json`) — or the PR host's issues — and link it from the reply.

8. Re-verify the gates

Same as `create-pr`, adaptive to the project: unit tests for touched files pass; `coverage-check` holds the project's bar with no regression; related e2e pass if user-facing and the project does e2e; lint clean; no suppressions to dodge a gate.

9. Watch for late feedback, then loop

Bots and CI often post minutes after a push. Right after pushing, run the bundled watcher in the background. It ships with the kit at `scripts/watch-pr-feedback.sh`; resolve its path from the kit install — `$CLAUDE_PLUGIN_ROOT` on Claude Code, the kit checkout path on Codex:

BASELINE=<ledger github ids> "$CLAUDE_PLUGIN_ROOT"/scripts/watch-pr-feedback.sh <pr>   # Claude Code
# Codex: run the same script from the kit's install path (no $CLAUDE_PLUGIN_ROOT there)

Read its exit code: **10** = new feedback (printed) → back to step 3 with t