Code Review
Overview
Code review has two failure modes: rubber-stamping (a single pass that reads the diff once and finds nothing) and noise (every technically-true observation reported as if it matters, burying the real issues under minor nits). This skill avoids both: work the diff against a concrete checklist, then verify every Blocker/Warning candidate before it reaches the report — a finding only earns its place if it's a real risk or a genuinely useful callout, not just something that happened to be true.
The approval standard: pass a change when it definitely improves overall code health, even if it isn't perfect. Don't fail a change because it isn't exactly how you would have written it. If it follows the project's conventions and moves the codebase forward, it passes.
When to Use
- Before merging any PR or change
- After completing a feature implementation or a bug fix (review both the fix and its regression test)
- When another agent or model produced code you need to evaluate
- When refactoring existing code
- NOT for exploratory/prototype code the user has explicitly marked as throwaway
Process
Phase 0 — Gather scope
Determine what's under review, in order of preference:
- A PR number, branch, or file path the user named — review that target.
git diff @{upstream}...HEAD(orgit diff main...HEAD/git diff HEAD~1with no upstream) — the committed range.- If there are uncommitted changes, or the range diff is empty, also run
git diff HEADand fold the working-tree changes into scope — review often runs before the commit exists.
Treat the resulting diff (or file set, for a from-scratch read) as the full review scope.
Phase 1 — Review against the checklist
Before writing a single finding, actually open and read every file this phase cites — in full, this run. Not from memory (plugin content changes between runs, and a prior review doesn't count as this one), and not via grep (a grep only surfaces lines containing your search term; it misses context, unstated-but-implied rules, and anything you didn't know to search for — a 30-line file is still a file you read top to bottom, not one you pattern-match against). This applies to every item below, not just the two checklists:
- Correctness, regression & risk —
references/code-review-checklist.md(correctness, removed-behavior/regression, cross-file impact, concurrency/idempotency, security, performance, test quality) - Code quality —
references/code-smells-checklist.md(Fowler-style smells, dead code, type safety, discriminated unions)
Plus two quick judgment calls that aren't fixed checklists, but still require reading their source material first, not just being named in See Also:
- Altitude — read
references/coding-patterns.mdfirst (the structural patterns — boundaries, decision/action separation, unrepresentable invalid states, useful errors), then look for a special case layered onto shared infrastructure instead of a deeper fix. Prefer generalizing the underlying mechanism over adding anotheriffor one more case. - Conventions (CLAUDE.md) — read, in full, every CLAUDE.md/AGENTS.md (or equivalent) file that governs the changed code (user-level, repo-root, any ancestor directory's own copy). Flag only a clear violation you can quote: the exact rule, and the exact line that breaks it. No style preferences, no "spirit of the doc" inferences.
Raise a candidate only if it clears the bar in references/code-review-checklist.md's "What's worth raising" section — a real risk, or a genuinely useful callout, not a minor nit that happens to be technically true. This is the main thing that keeps the report short and worth reading instead of padded with trivia. For each candidate that clears the bar, note file, line, a one-line summary, and — for anything in the Correctness/Regression/Risk checklist — a concrete failure_scenario (what input/state/timing triggers it, and what breaks).
Phase 2 — Verify Blockers and Warnings
Dedup candidates pointing at the same line or mechanism, keeping the one with the most concrete detail. For every candidate that would be reported as a Blocker or Warning, run one independent verification pass — via the Agent tool when available, with access to the diff and relevant files but not the Phase 1 reasoning — returning exactly one of:
- CONFIRMED — names the inputs/state that trigger it and the resulting wrong output or crash. Quotes the line.
- PLAUSIBLE — the mechanism is real but the trigger is uncertain (timing, environment, config). States what would confirm it.
- REFUTED — factually wrong (the code doesn't say that) or already guarded elsewhere. Quotes the line that proves it.
Keep CONFIRMED and PLAUSIBLE; drop REFUTED. Suggestions and Taste skip this step — they're optional by nature, so a wrong one costs the reader a glance, not a blocked merge; verifying them would just add process overhead for low-stakes findings.
Phase 3 — Report
Always produce the report in this exact structure:
## Code Review Report
### Blockers
- <file>:<line> — <description>. Fix: <suggested change>
Evidence: <traced input/state → code path → wrong output, or the spec line and the code that doesn't match it>
### Warnings
- <file>:<line> — <description>. Fix: <suggested change>
Evidence: <as above, or the rule broken plus its concrete cost>
### Suggestions
- <file>:<line> — <description>. Fix: <suggested change>
Evidence: <the rule broken, or what the code shows that makes it a problem>
### Taste
- <file>:<line> — <description>. Fix: <suggested change>
### Verdict
PASS / FAIL (FAIL if any Blocker remains)
If a section has no findings, write None under it — don't omit sections. Each finding states the file:line, the problem, the concrete failure scenario (for Blockers/Warnings), and — where there's an obvious one — the fix.
Every finding in Blockers/Warnings/Suggestions carries an Evidence: line — a finding that can't produce one goes under Taste instead, never into one of the real severities. Evidence means something concrete, not an assertion: for a correctness/risk finding, the traced input or state that reaches the wrong code path and the wrong output it produces (or, for a spec gap, the actual spec line quoted against the code that doesn't match it); for a quality/style finding, the specific rule or convention broken plus its concrete cost ("this N+1 adds ~50ms per item," not "this could be slow"). A claim that's really just a personal preference — no traceable bug, no named rule, no measurable cost — is Taste, not a Suggestion; say so plainly rather than dressing up an opinion as a finding with teeth.
- Blocker — must be fixed before the review passes: security vulnerability, data loss, broken functionality, a correctness bug with a confirmed or plausible trigger.
- Warning — should be fixed but won't block: a real but lower-stakes correctness/security/performance concern, an architecture issue worth raising.
- Suggestion — optional improvement, but still evidence-backed: cleanup, simplification, altitude, convention findings that cleared the "worth raising" bar and can point to a concrete rule or cost, not risks.
- Taste — a stylistic opinion with no hard evidence behind it. Never a Blocker, and skipped by Phase 2's verify step for the same reason Suggestions are — it's already the lowest-confidence tier by definition.
State the Altitude and Conventions conclusions explicitly, even when clean. A reader of the report can't tell "checked, no issue" apart from "not actually checked" unless the report says which it was — add one line for each, e.g. "Altitude: no special-case-on-shared-infrastructure pattern found" or "Conventions: reviewed against CLAUDE.md, no violations." This is also where a module/domain-boundary conclusion from references/code-review-checklist.md §3a belongs, when the diff touches cross-domain data — state it explicitly rather than letting a silent report imply nothing was wrong versus nothing was looked at.
If the review tooling exposes a structured findings reporter, call it once with the ranked list instead of writing the findings as prose.
Phase 4 — Record findings for future implementation
If any Blocker or Warning survived Phase 2 (Suggestions are too routine to log), append each one as a dated entry to review-findings/review-findings.md in the project's external output location (see references/external-output-paths.md) — a single running log for the project, always appended to, never overwritten or replaced per review. This file is never written inside the project's own repository, not even a gitignored path — resolve the actual external root first and write there directly, the same as every other artifact this plugin produces:
## <YYYY-MM-DD> — <what was reviewed: file/PR/branch/feature>
- **Category:** Correctness | Security | Performance | Concurrency | Quality
- **Finding:** <the specific bad pattern or problem observed, one line>
- **Avoid by:** <concrete guidance for next time — what to do instead, not just what was wrong>
Create the file (with a one-line header explaining its purpose) if this is the first entry for the project. Skip this step entirely on a clean review with nothing above Suggestion severity. Tell the user the entry was recorded and where, the same as any other external-output artifact.
This log exists so incremental-implementation, test-driven-development, subagent-driven-development, and code-writing agent personas can check it before starting new work and avoid repeating a mistake this project has already made once.
Dead Code Hygiene
After any refactor or implementation change, check for now-orphaned code: an old helper replaced by a new one, a component nothing renders anymore, a constant with no remaining references. List it explicitly and ask before deleting — don't leave it lying around, but don't silently remove something you're not sure is unused either.
Honesty in Review
- Don't rubber-stamp — "LGTM" without evidence of review helps no one.
- Don't soften a real issue — "this might be a minor concern" when it's a bug that will hit production is dishonest.
- Quantify problems when you can — "this N+1 adds ~50ms per item in the list" beats "this could be slow."
- Push back on approaches with clear problems; sycophancy is a review failure mode. Comment on the code, not the author.
- If the author has full context and disagrees after hearing the pushback, defer to their judgment — the goal is a better change, not a won argument.
Common Rationalizations
| Rationalization | Reality |
|---|---|
| "It works, that's good enough" | Working code that's unreadable, insecure, or architecturally wrong creates debt that compounds. |
| "I wrote it, so I know it's correct" | Authors are blind to their own assumptions. A second pass — especially an independently verified one — catches what a single read misses. |
| "We'll clean it up later" | Later rarely comes. Require cleanup before merge unless it's a genuine emergency. |
| "AI-generated code is probably fine" | AI code is confident and plausible even when wrong — Blockers and Warnings still need the verify step, not a skip. |
| "The tests pass, so it's good" | Tests are necessary but not sufficient — they don't catch architecture, security, or readability problems by themselves. |
| "This is technically true, I'll report it" | Technically true isn't the bar — references/code-review-checklist.md's "What's worth raising" is. A report padded with nits a senior engineer wouldn't mention is noise, not thoroughness. |
| "This finding felt right, I'll report it without checking" | Skipping Phase 2 for a Blocker/Warning is exactly how a review degrades into noise; an unverified candidate at that severity stays a candidate. |
| "The author already knows about this finding, no need to log it" | The log isn't for this author in this session — it's for whoever writes the next similar code, possibly a different agent with no memory of this conversation. |
| "I remember this skill's checklists from a previous review, I don't need to reopen them" | Memory drifts, and the plugin's content can change between runs. A review conducted without actually opening the checklist files this run is a review written from recollection, not from the checklist — open them every time. |
| "I grepped the CLAUDE.md/AGENTS.md for relevant-looking keywords, that counts as reading it" | A grep only returns lines containing your search term — it misses a rule stated in different words, context that changes what a rule means, and anything you didn't know to search for. Read the file; even a short one can hold a rule a keyword search would never surface. |
"coding-patterns.md is in See Also, I'll open it if I need it" |
For the Altitude call specifically, it's not optional further reading — Phase 1 requires reading it before making that call, every review, not only when something already feels off. |
| "I don't have hard evidence for this, I'll call it a Suggestion anyway — it's still worth mentioning" | That's exactly what the Taste tier is for — report it there instead of borrowing a Suggestion's credibility for an opinion that has no traced bug, named rule, or measurable cost behind it. |
| "Evidence is extra formatting, the description already says what's wrong" | A description without a traced input/output, a quoted spec line, or a named rule-plus-cost is an assertion, not evidence — the reader can't verify it without redoing the work themselves. |
Red Flags
review-findings.mdwritten inside the project's own repository (even a gitignored path) instead ofreview-findings/review-findings.mdat the external output location- A review that only checks whether tests pass, ignoring correctness/security/quality
- A Blocker or Warning reported without an independent verify pass (no CONFIRMED/PLAUSIBLE/REFUTED)
- A report padded with Suggestions that don't clear the "worth raising" bar — technically true but not something a senior engineer would actually say
- "LGTM" without evidence of actual review
- Security-sensitive changes reviewed without working through the Security section of the checklist
- A large diff that's "too big to review properly" — ask the author to split it instead of skimming
- No regression test accompanying a bug-fix PR
- The report missing the PASS/FAIL verdict, or a FAIL verdict with no Blocker listed
- A review written from memory, without having actually opened this run's copy of
code-review-checklist.md,code-smells-checklist.md, orcoding-patterns.md - Project conventions "checked" by grepping CLAUDE.md/AGENTS.md for keywords instead of reading the file in full
- The Altitude judgment call made without first reading
references/coding-patterns.md - A report silent on Altitude, Conventions, or module-boundary conclusions instead of stating explicitly that each was checked and found clean
- A Blocker, Warning, or Suggestion with no
Evidence:line, or one that's just a restatement of the description rather than a traced path/rule/cost - An evidence-free opinion reported as a Suggestion instead of Taste
- A Taste finding marked as a Blocker, or sent through Phase 2 verification
- An atomicity problem (a multi-write sequence needing all-or-nothing) fixed with hand-rolled cleanup/recovery instead of a recommended transaction
- A test that can't actually fail (trivially true assertion, unchecked promise, a self-satisfying mock) reported as anything less than a Blocker
Verification
- Scope was gathered correctly (diff, working tree, or named target — not guessed)
- The diff was worked against both checklists (
code-review-checklist.mdandcode-smells-checklist.md), plus the Altitude and Conventions judgment calls - Every reported candidate clears the "worth raising" bar — no padding with technically-true-but-irrelevant nits
- Every Blocker/Warning passed an independent verify step (CONFIRMED or PLAUSIBLE); Suggestions and Taste were not required to
- Every Blocker/Warning/Suggestion carries an
Evidence:line (traced path, quoted spec line, or named rule + cost) — anything that couldn't produce one was moved to Taste instead - A multi-write atomicity need was flagged with a transaction recommended, not hand-rolled recovery logic accepted as the fix
- Any test that can't actually fail was reported as a Blocker, not a lower severity
- The report follows the exact Blockers/Warnings/Suggestions/Taste structure, with
Nonewhere a section is empty - The report ends with an explicit PASS/FAIL verdict (FAIL only if a Blocker remains)
- Any Blocker/Warning was appended to
review-findings/review-findings.mdat the external output location — never a path inside this project's own repository — or the review had none, and this step was correctly skipped
See Also
references/code-review-checklist.md— the Correctness, regression & risk checklist this skill's Phase 1 works throughreferences/code-smells-checklist.md— the Code quality checklist (Fowler-style smells, dead code, type safety)references/security-checklist.md— deeper security review guidance, for a specific finding worth a closer lookreferences/performance-checklist.md— deeper performance review guidance, for a specific finding worth a closer lookreferences/coding-patterns.md— structural patterns worth checking for on the Altitude judgment call (boundaries, decision/action separation, unrepresentable invalid states, useful errors)
