| name | review-staged-changes |
| description | Review Git staged changes for correctness risks and concrete maintainability, readability, and simplification opportunities without modifying files or rerunning tests. Use when asked to review the index, staged diff, pending commit, or pre-commit changes while assuming the test suite has already passed. |
Review Staged Changes
Review only the Git index. Treat tests as passed, remain read-only, and lead with actionable findings that improve correctness and make the code easier to understand and change safely.
Throughout, delegate means hand the work to a less expensive subagent (e.g. Sonnet, GPT-5.5-medium) and reserve your own reasoning for synthesis and final judgment.
Inspect the change
Delegate the following groundwork to the subagent first:
- Read the repository instructions, then any instructions scoped to changed directories.
- Inspect
git status --short, git diff --cached --name-only, and git diff --cached --stat.
- Read the complete staged diff with
git diff --cached --. Split it by component when useful.
- Read surrounding staged source with
git show :path/to/file when the working tree may differ from the index.
- Trace changed behavior across callers, types, persistence, API boundaries, UI state, and staged tests. Read unchanged context only when needed to establish impact.
Do not review unstaged changes as part of the patch. Do not edit files, stage changes, run tests, builds, linters, or formatters. Read-only structural checks are acceptable when they answer a specific review question.
Find correctness risks
Prioritize observable failures over style:
- Lost validation, changed error classification, or ambiguous request shapes
- Partial commits, unsafe retries, rollback mistakes, or duplicate side effects
- Async races, stale state, cancellation gaps, and cleanup ordering
- Fabricated or duplicated state drifting from an authoritative source
- API, type, persistence, or UI assumptions that no longer agree
- Data loss, security regressions, or behavior contradicted by repository instructions
For each risk, identify the triggering path and user-visible or operational impact in natural language, and describe how they can be reproduced. Do not infer a defect solely from missing tests.
Improve maintainability and readability
Recommend an improvement when the staged design makes future changes harder, forces readers to hold unnecessary context, or obscures an important invariant. Prefer structural clarity but still look for opportunities to simplify the code. Work one theme at a time and look especially for:
Single source of truth: one fact, represented and derived in one place.
- One concept represented by multiple types, fields, callbacks, or sources of truth
- Duplicate policy, validation, transformation, or error handling likely to drift
- Authoritative data discarded and reconstructed, reread, refreshed wholesale, or fabricated later
Contracts and invariants: the declared shape matches runtime behavior, and invariants are enforced once at a boundary.
- Names, types, comments, and runtime behavior that describe different contracts
- Important invariants enforced late, repeatedly, or only by callers instead of at one boundary
- Tests coupled to incidental implementation details or fixtures that conceal the production contract
Responsibilities and control flow: clear ownership, with no flow hidden behind indirection.
- Responsibilities split across layers without a clear owner, or unrelated concerns interleaved in one function
- Excessive indirection, pass-through wrappers, broad interfaces, or callbacks that hide the real control flow
Simplification through a smaller design: less code, fewer branches, reusable units.
- Long branching paths that can become a direct operation by strengthening an earlier invariant
- Comments that narrate complexity which can instead be removed through a smaller design
- Complicated in-function logic that can be distilled into separate functions, particularly reusable ones
- Excessively long code files that can be logically split into util files, particularly reusable ones
After drafting the findings for a theme, delegate that group's draft to the subagent to check your reasoning and surface additional opportunities within the same theme before moving on. Fold its confirmed additions into the group.
Do not report formatting preferences or subjective style in isolation. For each maintainability finding, name the future change, debugging task, or invariant that is unnecessarily difficult to reason about.
Report findings
Order findings by severity. For each finding:
- State the problem or improvement opportunity in one sentence.
- Cite the staged file and line nearest the cause.
- Explain the concrete runtime impact or maintenance/readability cost.
- Suggest the simpler direction, not a full implementation plan.
Use P0 through P3 when defect severity helps prioritization; label non-defect improvements Maintainability when a severity would be misleading. Group small related cleanup into one item. If no concrete findings remain, say so plainly and mention only material residual uncertainty.
After correctness reports, write a section on maintainability, readability, simplification opportunities, and cleanup.
