git:20260831.64fb3ee to git:20260922.be562dc

---

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)"

---

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