git:20260722.0902745 to git:20260728.989f66c

36 added, 26 removed. Audit A to A.

---

name: fix-pr

- description: Resolve the findings on an existing pull request - review comments, CI failures, and self-review findings - then re-verify the quality gates and push. Use when a PR has unresolved review feedback or failing checks, or as the fix step after pr-review.

+ 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

- Turn findings into commits: every blocking finding gets fixed or explicitly answered, gates go back to green, and the PR ends ready for re-review.

- ## Gather the findings

+ 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.

- Collect, in this order:

+ ## 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.

- Fetch these from the configured host (`prHost` in `.claude/dev-kit.json`) — commands below are for `github`; for **bitbucket** use the REST API (`/pullrequests/{id}` for comments, `/statuses` for build results) with a token from the environment, and for **gitlab** use `glab mr view/checks`.

+ ## 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 comments**: `gh pr view <pr> --comments` and unresolved review threads (`gh api` for review comments when needed).

- 3. **Self-review findings** handed over by the caller (e.g. the coding-agent's `pr-review` pass).

+ 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).

- Deduplicate and classify each finding: **blocking** (correctness, security, contract drift, failing gate) vs **non-blocking** (style, suggestion, question).

+ ## 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):

- ## Resolve

- For each blocking finding:

+ 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.

- 1. Fix it in code, following the repo's conventions and the kit instructions (`instructions/secure-coding.md`, `instructions/testing-standards.md`).

- 2. Add or update the tests that prove the fix; keep touched files at ≥ 95% coverage.

- 3. If you believe a finding is wrong, do not ignore it — draft a reasoned reply, **show it to the user and get confirmation before posting it** on a human reviewer's thread (in `--auto-approve` pipeline runs, post it and flag it prominently in the final report instead). Let the reviewer decide.

+ **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.

- For non-blocking findings: apply the cheap ones, answer the rest on their threads. Never resolve someone else's thread without either a fix or a reply.

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

- ## Re-verify (same gates as create-pr)

+ ## 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.

- - Unit tests for touched files pass.

- - `coverage-check` still ≥ 95% on every touched file.

- - Related e2e tests pass if user-facing behavior changed.

- - Lint clean. No suppressions added to dodge a gate.

+ ## 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.

- ## Ship the fixes

+ ## 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.

- 1. Commit with a message referencing what was addressed (e.g. `fix: PROJ-1234 address review findings — <short list>`).

- 2. Push to the PR branch.

- 3. Comment a short summary on the PR: findings addressed (with commit refs), findings answered-not-fixed (with reasoning), verification evidence.

+ ## 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.

- ## Report

+ ## 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.

- Findings fixed / answered / remaining, verification results, and the PR URL. If any blocking finding could not be resolved, say so explicitly with the reason — never report the PR as clean while threads remain open.

+ ## 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 plugin at `"$CLAUDE_PLUGIN_ROOT"/scripts/watch-pr-feedback.sh`):

+ ```bash

+ BASELINE=<ledger github ids> "$CLAUDE_PLUGIN_ROOT"/scripts/watch-pr-feedback.sh <pr>

+ ```

+ Read its exit code: **10** = new feedback (printed) → back to step 3 with the new items; **20** = a bot signalled all-clear (👍 on the PR / approving review); **0** = ten quiet minutes; **30** = inconclusive → re-run it. Only close out on **0** or **20** from a window covering the last push. (GitHub only; for other hosts, do a single post-push re-check instead.)

+ ## 10. Report

+ Account for **every** ledger row (fixed / deferred+issue link / discarded+why / answered), the verification evidence, how the feedback window closed, and the PR URL. Never report the PR clean while blocking threads remain open.