resolve-review-comments git:20260922.be562dcA

Immutable. This exact content never changes and is served at /api/v1/blob/e855911d85c92cfb.

---
name: resolve-review-comments
description: Triage, fix or rebut, then reply-and-resolve every review comment on a pull request, including AI-review bot findings (Codex, Copilot, Gemini). Use when the user wants to address, respond to, action, or clear the review comments on a PR.
argument-hint: "A PR number or URL (defaults to the PR for the current branch)"
allowed-tools: "Bash(gh pr view *) Bash(gh pr diff *) Bash(gh api *)"
---

# Resolve Review Comments

Take every review comment on a pull request to a **resolved** end state: each one is
either **fixed** (code changed, with a test) or **rebutted** (a one-line reason it is
not a defect), then replied to and its thread resolved. No thread is left open and no
finding is actioned on faith.

A review comment is a claim, not an instruction. Bots (Codex, Copilot, Gemini) are
confidently wrong often enough that **every finding earns its verdict from the code,
the spec, the tests, and the permission model, never from the comment's own say-so.**

## 1. Gather every thread

Resolve the repo (`gh repo view --json nameWithOwner`) and the PR number (from the
argument, or `gh pr view --json number` for the current branch). Pull all three comment
surfaces (reviews, inline review threads, general issue comments) and the PR's
commit range. See [`references/gh-mechanics.md`](references/gh-mechanics.md) for the exact
`gh api` and GraphQL calls; you need it whenever you touch the GitHub side.

Completion criterion: a list of every unresolved thread, each with its comment id,
GraphQL thread id, file:line, reviewed commit, and body.

## 2. Note the reviewed commit, then cluster

Each bot reviews **one commit**. Compare it to current `HEAD`: a finding on an older
commit may already be fixed, or point at code that has since moved. Re-anchor every
comment to the current code before judging it.

Then **cluster duplicates**: two bots flag the same line for the same reason constantly.
Judge and fix a cluster once; reply to and resolve every thread in it.

## 3. Triage each cluster: `legit` or not

A finding is **legit** only when you can name the concrete failure it causes, the
inputs, the wrong result. Read the cited code and its neighbours, then the governing
truth: the spec/CONTEXT, the tests around it, and the **permission/role model** for
anything about authorization. Land one verdict per cluster:

- **legit**: a real defect or a correctness/security improvement you can demonstrate.
- **not a bug**: a false positive, already-fixed-at-HEAD, or **spec-sanctioned**
  behaviour the reviewer misread. Capture the one-line evidence now (the spec line, the
  role that lacks the leaf, the test that already asserts it).

The trap is the plausible-but-wrong "fix." A change that satisfies a comment while
breaking a legitimate workflow is worse than the finding. Before you commit to fixing:
would the fix block a role or path the system intends to allow? **An existing green
test that your fix turns red is the tell**; the finding is likely over-strict; treat
that as evidence for a rebuttal, not a test to edit away.

## 4. Fix the legit ones

Change the code, and add or extend a test that **fails without the fix and passes with
it**; a behaviour change with no test proving it is not done. Run the affected tests
green. For a race or concurrency claim, drive the interleaving deterministically (write
the conflicting state, then act on a stale in-memory model) rather than asserting timing.

If proving a guard needs a disproportionately brittle harness, and the guard is a
byte-identical mirror of one already tested elsewhere, say so in the reply and lean on
that parity instead of shipping a flaky test, but this is the rare exception, not the
default escape hatch.

Completion criterion: every legit cluster has a code change and a green test (or a
stated parity rationale); run the project's Filament/lint/static checks the repo
expects on touched files.

## 5. Commit and push

Commit the fixes with a message that states, per cluster, what changed and, for the
rebutted ones; that they were reviewed and why they stand. Push to the PR branch so the
threads resolve against the pushed state.

## 6. Reply and resolve every thread

For each thread, post a reply then resolve it (mechanics in the references file):

- **fixed** → name the commit and the behaviour now, and the test that pins it.
- **not a bug** → the one-line evidence from step 3 (cite the spec line, the role/leaf,
  or the existing test).

Keep reply bodies free of apostrophes and backticks so a shell heredoc or `-f body=`
cannot mangle them; batch the reply+resolve pairs through one script.

Completion criterion: the PR reports **zero unresolved review threads** (re-query to
confirm), every reply is posted, and `git status` is clean. Report the tally: fixed vs
rebutted, and the commit that carried the fixes.