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