review

name	review
description	Review code for potential issues and improvements. Use when asked to review specific files, functions, or code sections.
allowed-tools	Bash, Read, Glob, Grep, Edit, Write, WebSearch

Code Review

Documented in depth: Most AI code reviews are noise. Here's how to fix that.

Review the mentioned code for potential issues and improvements.

Review critically — don't assume correctness. Question every design choice and flag anything that would fail a production code review. Assume any prior git state or file contents you gathered is stale, especially if the user re-runs this skill or asks you to re-read.

Before you start

Study the project's coding standards and design principles — e.g. CLAUDE.md, AGENTS.md, or design docs in the repo, if present.

Only report verified bugs — things that are actually wrong. Do NOT report:

• Style, organization, or naming preferences
• Speculative future risks ("if someone later removes this guard...")
• Feature requests or suggestions disguised as issues
• Things you haven't proven with concrete evidence from the codebase
• Anything a linter, typechecker, or compiler will catch — CI handles those
• Issues the code explicitly silences (// eslint-disable, # noqa) — the author already made that call
• Real issues on lines the change does not touch — out of scope

For EVERY potential issue, you MUST complete these steps before reporting:

1. Read the actual code (not just the diff) — follow the full call chain
2. Search for all callers/usages to understand context
3. Read any design docs or plans that explain the rationale
4. Construct a concrete failing scenario — if you can't describe exactly how the bug manifests, it's not an issue
5. Discard it if your research shows it's intentional or already handled

Use subagents along two axes: perspective and mode.

Perspectives (run in parallel, one subagent each):

• CLAUDE.md / design-principles compliance — audit the change against the project's written guidance
• Shallow bug scan — read just the diff and flag obvious logic errors, off-by-ones, missing awaits, etc.
• Historical context — git blame and git log on the changed lines. Understand why the code is the way it is before suggesting it should be different. Check prior PR comments on the same files; past review consensus often still applies
• In-code constraints — read comments adjacent to the change. They often spell out invariants the diff alone doesn't reveal

Modes:

• Exploration: When more than three files need review, or the code is complex, launch Explore subagents (one per file/area) to gather findings
• Validation: Before reporting ANY issue, launch a subagent to verify it — have it trace the full call chain, search for guards/handlers you might have missed, and read the relevant design docs. If the subagent can't confirm the bug, discard the issue
• Iteration: After your initial analysis, launch a second round of subagents to dig deeper into the most promising findings — check edge cases, race conditions, and interaction effects between the changed files

If you find zero real issues after thorough research, say "No issues found." Do not pad the list.

What to look for

Correctness

• Logic or implementation errors
• If correct but surprising, suggest a clearer equivalent or a comment
• Don't trust docs or implementation as authoritative — if they disagree, flag it, consider what you think is correct (it may be neither!), and explain your reasoning

Code quality

• Violations of the project's design principles or coding standards
• Dead code (suggest deleting it)
• Comments that merely restate the function name (suggest removing)

Testing gaps

• Missing coverage for critical paths or edge cases

Response format

1. Completely omit any issues that are irrelevant after research and analysis.
2. Sort remaining issues by severity (Critical > High > Medium > Low).

Step 1 — write up every issue as text first. For each issue use a short ID (e.g. #A, #B) and include:

• Priority: Critical / High / Medium / Low
• Problem: What's wrong, why, and the concrete scenario where it fails
• Proof: The specific code path or test that demonstrates the bug
• Solution: A concrete fix
• Location: File and line reference

Step 2 — only after all issue blocks are written, use AskUserQuestion so the user can accept, veto, or comment on each one. The question text is just the ID (e.g. Accept #A?) — it is NOT a substitute for the write-up above. Never jump straight to AskUserQuestion without the text write-up; the user can't evaluate #A if they've never seen what #A is.

Edit, Write, and Bash are available so that, once the user accepts a finding, Claude can apply the fix and run tests to prove the bug and validate the fix in the same session. The proof-before-reporting discipline is what keeps this from turning into drive-by "improvements."

Adapting for your project

• Replace "the project's coding standards and design principles" with explicit paths (CLAUDE.md, docs/DESIGN-PRINCIPLES.md, etc.).
• Add project-specific "what to look for" items (e.g. "new public APIs have rate limiting", "DB queries use parameterized inputs", "error messages don't leak internal paths").
• Tune the exclusion list if your team does want style or refactor feedback. The default is strict because noise is the bigger problem.