code-review

Code Review

Review changed code for reuse, quality, and efficiency. Fix real issues. Skip false positives.

CRITICAL: Start from the diff, not the whole codebase. Review what changed, not everything.

Phase 1: Identify Changes

1. Run git diff (or git diff HEAD if there are staged changes) to see what changed.
2. If there are no git changes, review the most recently modified files the user mentioned or that were edited earlier in the conversation.
3. Note the scope: which files, which modules, how many lines. This calibrates review depth.

Phase 2: Three Parallel Review Passes

When the diff is non-trivial (>50 lines or touches >3 files), launch three review agents in parallel via the Agent tool. Pass each agent the full diff so it has complete context.

For small diffs, run the three passes yourself sequentially — subagent overhead isn't worth it.

Pass 1: Code Reuse

For each change:

• Search for existing utilities and helpers that could replace newly written code. Check utility directories, shared modules, and files adjacent to the changed ones.
• Flag new functions that duplicate existing functionality. Name the existing function to use instead.
• Flag inline logic that could use an existing utility — hand-rolled string manipulation, manual path handling, custom environment checks, ad-hoc type guards.

Tool strategy for finding existing code:

• Glob to locate utility directories and shared modules (near-zero tokens)
• Grep with -C 3 for function signatures similar to what was written (lightweight)
• Read only files Grep confirmed as relevant (heavy)

Pass 2: Code Quality

Review for these specific smells:

• Redundant state: state that duplicates existing state, cached values that could be derived, observers/effects that could be direct calls
• Parameter sprawl: adding new parameters to a function instead of generalizing or restructuring
• Copy-paste with variation: near-duplicate code blocks that should be unified with a shared abstraction
• Leaky abstractions: exposing internal details that should be encapsulated, or breaking existing abstraction boundaries
• Stringly-typed code: using raw strings where constants, enums (string unions), or branded types already exist in the codebase
• Unnecessary JSX nesting: wrapper elements that add no layout value — check if inner component props already provide the needed behavior
• WHAT comments: comments explaining what the code does (well-named identifiers already do that), narrating the change, or referencing the task/caller. Keep only non-obvious WHY (hidden constraints, subtle invariants, workarounds)