| name | code-review |
| description | Use when the user mentions reviews, GitHub reviews, PR feedback, review comments, "address the reviews", "reviews are here", "code review", or asks to respond to reviewer comments. Loads a rigorous workflow: read every review, attempt to disprove each element with codebase evidence, then decide to apply/skip/disprove. Addresses issues even outside the PR scope since reviewers examine the broader codebase. |
Code Review — Disprove-First Workflow
When a user asks you to address code reviews, follow this rigorous methodology. The default stance is skeptical: every review comment is guilty of being wrong until proven correct.
Step 0 — Detect Review Context
The user may provide reviews in several ways. Determine the source:
| User says | Source |
|---|
| "reviews are here", "address the reviews" (with no link) | Ask the user where the reviews are |
Links to a GitHub PR (github.com/.../pull/...) | Use gh pr view and gh pr diff |
| Pastes review text in chat | Parse directly from the conversation |
| "check the review comments" on current branch | Use gh pr view --comments or gh api |
IMPORTANT: If the user mentions reviews but provides no link or text, ASK them to provide it. Do not guess.
GitHub PR Review Fetching
To fetch all reviews and review comments from a GitHub PR:
gh pr view --json number,title,url
gh pr view --json reviews --jq '.reviews[] | {author: .author.login, state: .state, body: .body}'
gh api "repos/:owner/:repo/pulls/$PR_NUMBER/comments" --jq '.[] | {path: .path, line: .line, author: .user.login, body: .body}'
gh pr diff
Aggregate ALL review feedback (approval comments, change requests, inline comments) before proceeding.
Step 1 — Read All Reviews, Extract Every Claim
Read EVERY review comment. Do not skip any, even brief ones. For each review comment, extract discrete claims — a single review comment may contain multiple claims.
A claim is an actionable statement: a bug report, a style violation, a design criticism, a request for a change. Treat each claim independently.
Catalog them in your internal reasoning. Tag each claim with:
- Source: which reviewer, inline vs top-level
- Location: file path and line range if applicable
- Type: bug | style | design | performance | correctness |
Step 2 — Attempt to DISPROVE Every Claim
For every claim, BEFORE deciding whether to apply it, attempt to prove it wrong using evidence from the codebase. This is the most critical step.
Techniques for Disproving
Search existing code for counter-examples:
- Does the codebase already follow a different pattern?
- Is the reviewer suggesting something that contradicts existing conventions?
- Is there a utility/helper the reviewer is unaware of that makes their suggestion moot?
Check the broader codebase context:
- Does the claim apply to 10+ other files the reviewer didn't notice? If so, it's a broader refactor — not this PR's responsibility.
- Is the reviewer's suggested approach already tried and reverted in git history?
Verify factual correctness:
- Is the reviewer's stated behavior actually observable?
- Does the reviewer claim a bug that doesn't reproduce?
- Is the reviewer's understanding of the code flow incorrect?
Check consistency with project architecture docs:
- Does
AGENTS.md or the project README prescribe a different approach?
- Does the reviewer's suggestion violate documented layer dependency rules?
Evidence Thresholds
| Confidence | Evidence | Action |
|---|
| Disproven | Codebase conclusively contradicts the claim | Explain why the reviewer is wrong. Do NOT apply. |
| Weak | Reviewer's point has merit but counter-evidence exists | Flag as "questionable" — ask the user if they want to apply |
| Uncertain | Neither proven nor disproven | Apply the change (defer to reviewer expertise) |
Never disprove based on opinion. If it's a style preference and the reviewer disagrees, the reviewer wins. Only disprove when codebase evidence contradicts factual claims.
Step 3 — Decide: Apply or Skip
For every claim you cannot disprove, decide:
Apply When:
- The claim identifies a genuine bug
- The claim fixes a violation of project conventions (check AGENTS.md, existing code)
- The claim improves correctness without regressing other concerns
- The claim is a scope expansion AND the reviewer is right that the issue matters
- The claim is minor and has no downside
Skip When:
- The claim is a style preference that contradicts existing codebase style
- The claim would require touching 15+ unrelated files (flag as follow-up issue)
- The claim is already addressed by a different PR or commit
- The claim is factually wrong (see Step 2)
- The claim is purely cosmetic with zero user-facing impact AND project doesn't prioritize cosmetics
Scope Expansion — Special Rule
Reviewers often point out issues in code adjacent to the PR changes — files or patterns NOT modified in the PR. This is legitimate. The reviewer is examining the broader codebase health, not just the diff.
You MUST address scope-expansion claims if:
- The issue exists in the code your PR touches (even if pre-existing)
- The issue could cause bugs, crashes, or data loss
- The issue violates fundamental project architecture rules
You MAY skip scope-expansion claims if:
- The issue is cosmetic and pre-existing across dozens of files
- The issue is a known trade-off documented in the project
When skipping, tell the user: "This review point is valid but outside scope. It affects N files and deserves its own PR. I recommend filing it as a follow-up issue."
Step 4 — Present Your Findings
Before making ANY changes, present a summary to the user:
## Review Analysis — [PR Title]
### Reviews Found: N comments from M reviewers
#### ❌ Disproven (will not apply)
- [Claim] — reason it's wrong with codebase evidence
#### ⚠️ Skipped (valid but not applying)
- [Claim] — reason for skipping
#### ✅ Will Apply (proceeding to implement)
- [Claim] — brief description of what will change
Wait for the user to review before implementing, UNLESS the user explicitly said "just do it" or similar.
Step 5 — Implement Changes
For each "apply" claim, make the change following project conventions:
- Use existing patterns and utilities
- Maintain the same code style as surrounding code
After implementing all changes, run the project's build/lint/typecheck commands to verify nothing is broken.
Anti-Patterns — Never Do These
- Do NOT apply every review comment without scrutiny
- Do NOT argue with reviewers about style preferences — if it's subjective, apply it
- Do NOT silently skip review comments — always explain why
- Do NOT refactor unrelated code while addressing reviews (unless the reviewer asked)
- Do NOT treat scope-expansion claims as automatically out-of-scope — they are valid
- Do NOT make changes without understanding the full context of each claim
