review-staged

name	review-staged
description	Review the git staged diff for verified bugs before committing, then drive a clean Conventional Commit.
allowed-tools	Bash, Read, Glob, Grep, Edit, Write, WebSearch

Review Git Staged Changes

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

Review the staged diff (git diff --cached) 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 and 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

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 liberally:

• Exploration: When more than three files are staged, 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 issue, discard it
• 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
• Refinement: Are all the staged diffs a single coherent "story" or "theme"? If not, recommend how they should be split into separate commits before committing.

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 add 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
• Doc comments that have drifted from the implementation, or that merely restate the function name (suggest removing)
• Dead code — suggest deleting it

Testing & documentation

• Missing coverage for critical paths or edge cases
• Test fixture updates if needed

Response format

1. Discard any issues that turned out to be noise after research.
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 unique ID (e.g. #A, #B) and include:

• Priority: Critical / High / Medium / Low
• Problem: What's wrong 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 to collect accept/veto decisions. 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.

Post-review commit flow

Do NOT commit directly after the review. Follow these steps in order:

1. List the files (and line ranges, if partial) that are staged for commit.
2. Compose a Conventional Commits message and use AskUserQuestion to let the user edit it before committing.
   • Focus on the why, not the what — the diff already shows what changed. One sentence on motivation or consequence beats a list of renamed files.
3. Only commit after explicit user approval.