Code Review

Comprehensive code review checking for regressions, duplicated logic, and specification compliance.

Invocation Modes

Mode 1: Working Tree Review (default)

/review

Reviews uncommitted changes in the working tree.

Mode 2: Specific Files/Directories

/review --files app/services/ app/routes/news.py

Reviews specific files or directories regardless of git status.

Mode 3: Commit Review

/review --commit abc123
/review --commit HEAD~3..HEAD

Reviews all files changed in a specific commit or commit range.

Mode 4: Spec Compliance (Full Codebase)

/review docs/feature_spec.md

Reviews ALL code relevant to the specification document.

Mode 5: Spec Section (Full Codebase)

/review docs/feature_spec.md#"Section Name"

Reviews ALL code relevant to a specific section of the spec. The section name should match a markdown heading in the document.

Combined Modes

/review --commit abc123 docs/spec.md

Review files from a commit against a spec document.

Review Process

Step 1: Determine Scope

Parse arguments:

• No args: git diff --name-only (working tree)
• --files <paths>: use specified paths
• --commit <ref>: git diff --name-only <ref>^..<ref> or git diff --name-only <range>
• Spec path: read spec, find all relevant code in codebase

If spec provided:

• Read the spec document (or specified section)
• Identify all files in the codebase that implement the spec
• Use Grep/Glob to find relevant code paths

Step 2: Regression Check

1. Run tests

   pytest tests/unit -q
   pytest tests/integration -q  # if touching DB/routes
   

2. Analyze removals (for working tree or commit modes)

   • Check git diff for removed functions/classes
   • Verify removed code isn't used elsewhere
   • Flag any removed error handling or validation

3. Check for breaking changes

   • API signature changes
   • Database schema changes
   • Configuration changes

Step 3: Duplication Scan

For each new function or significant code block:

1. Extract key patterns (function names, logic patterns, string literals)
2. Search codebase for similar implementations:

   # Example: find similar function names
   grep -r "def.*similar_name" app/
   

3. Flag potential duplications with locations
4. Suggest consolidation if appropriate

Step 4: Spec Compliance (if spec provided)

1. Parse requirements from the spec document

   • Extract explicit requirements (MUST, SHOULD, etc.)
   • Identify acceptance criteria
   • Note any constraints or edge cases mentioned

2. Map requirements to code

   • For each requirement, find implementing code
   • Verify the implementation matches the spec

3. Gap analysis

   • List any spec requirements not implemented
   • Flag any implementations that deviate from spec
   • Note any code that isn't covered by the spec (scope creep)

Output Format

Structure the review as:

## Review Summary
- **Scope**: [working tree / files: X / commit: abc123 / spec: document name]
- **Files reviewed**: N files
- **Tests**: PASSED / FAILED (with details)

## Regressions
- [ ] Issue 1: description (file:line)
- [x] No regressions found

## Duplications
- [ ] `function_name` in file1.py is similar to `other_func` in file2.py
- [x] No significant duplications found

## Spec Compliance (if applicable)
### Implemented
- [x] Requirement 1: implemented in file.py:123

### Missing
- [ ] Requirement 2: not found in codebase

### Deviations
- [ ] Requirement 3: spec says X, but code does Y

## Recommendations
1. Specific actionable recommendation
2. ...

Section Parsing

When a section is specified with #"Section Name":

1. Read the full document
2. Find the heading matching the section name (case-insensitive)
3. Extract content from that heading until the next heading of equal or higher level
4. Use only that content for spec compliance checking

Example:

/review docs/roadmap.md#"News Feed"

Would extract the "News Feed" section and all its subsections.

Commit Range Examples

# Single commit
/review --commit abc123

# Last 3 commits
/review --commit HEAD~3..HEAD

# All commits on current branch vs main
/review --commit main..HEAD

# Specific range
/review --commit v1.0.0..v1.1.0

When to Invoke Proactively

Consider running this review automatically when:

• Completing a feature implementation
• Making changes to core services or models
• Refactoring existing code
• Before suggesting the work is complete

Ask the user if they'd like a review after significant changes.