Resolve Review Comments

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