review-code

name	review-code
description	Review code changes for correctness, security, error handling, performance, testing, and more. Dynamically selects review perspectives based on what changed. Outputs a structured review document.
argument-hint	<optional: file path, "staged", "all" (default), or glob pattern>

Review code changes and produce a structured review document with prioritized findings. Dynamically selects which review perspectives to apply based on the code being reviewed.

Input

The user may provide: $ARGUMENTS to specify what to review:

• No argument or all: Review all uncommitted changes (staged + unstaged + untracked new files)
• staged: Review only staged changes
• A file path: Review only that specific file
• A glob pattern: Review matching files

If there are no changes to review, inform the user and exit.

Process

---

Phase 1: Gather Changes

1. Determine scope based on arguments

   • If $ARGUMENTS is empty or all: Get all uncommitted changes
   • If $ARGUMENTS is staged: Get only staged changes
   • If $ARGUMENTS is a file path: Read that file
   • If $ARGUMENTS is a glob: Match files

2. Collect the diff and file contents

   • Run git diff HEAD for unstaged changes
   • Run git diff --cached for staged changes
   • Run git status --porcelain to identify untracked files
   • Read full contents of new (untracked) files
   • For file-specific reviews, read the entire file

3. Identify what changed

   • List of modified/new/deleted files
   • Languages and file types present
   • Approximate diff size (lines changed)

Phase 2: Select Review Perspectives

You have 10 review perspectives available. Always apply Correctness & Logic. Then select 2-4 additional perspectives based on what's in the diff. Apply the most relevant set — not all 10.

Available perspectives and when to select them:

Perspective	Select When
Correctness & Logic	Always selected
Security	Auth code, input handling, crypto, API endpoints, env/config, SQL, shell commands, secrets, or file handling
Error Handling & Resilience	Try/catch blocks, error types, API calls, I/O operations, distributed systems, retry logic
Performance & Scalability	DB queries, loops over collections, caching, concurrent/async code, hot paths, large data processing
Testing Quality	Test files in diff, OR logic changed without corresponding test changes
API Design & Contracts	Endpoint definitions, protobuf/OpenAPI, public function signatures, type definitions, SDK code
Maintainability & Readability	Large diffs (>300 lines), new modules, refactors, complex control flow
Concurrency & Thread Safety	Goroutines, async/await, shared state, channels, locks, atomics, thread pools
Data Model & Schema	Migration files, ORM models, SQL schema, protobuf defs, data transfer objects
Observability	Logging changes, metrics code, tracing, health checks, monitoring config

Selection rules:

1. Always include Correctness & Logic
2. Score each remaining perspective by counting signals in the diff: keywords, file types, file paths, patterns
3. Select the top 2-4 additional (3-5 total)
4. Notable absences count too: logic changed without test files → Testing Quality is relevant

State your selections before reviewing:

Perspectives applied: Correctness & Logic, Security, Error Handling (3 of 10)

• Security: changes touch auth middleware and JWT validation
• Error Handling: new API client code with external service calls

Phase 3: Review Code

Apply each selected perspective. The detailed review criteria for each perspective are defined in perspectives.md. For each perspective, only check what that perspective owns — don't duplicate effort across perspectives.

Always-applied check — Design Document References: Scan all changed code (including comments, test names, commit messages, and string literals) for numeric references to design documents. Flag any of the following as Warning findings:

• Requirement IDs (e.g., FR-1.2.3, REQ-001, NFR-2.1)
• Section numbers from design docs (e.g., Section 3.2, §4.1)
• Any other opaque numeric identifiers that reference design documents rather than describing the requirement or design decision in plain language

These references are meaningless to someone reading the code without the design docs open. The fix is always the same: replace the ID with a plain-language description of what the requirement or design decision actually is.

Categorize every finding by severity:

1. Critical — Must fix before merge

   • Security vulnerabilities
   • Breaking changes
   • Data loss risks
   • Logic errors causing incorrect behavior
   • Race conditions with data corruption risk

2. Warning — Should fix

   • Missing error handling
   • Performance issues
   • Test gaps
   • Convention violations
   • Resource leaks

3. Suggestion — Consider improving

   • Naming improvements
   • Minor optimizations
   • Documentation additions
   • Style preferences

Phase 4: Write Review Document

1. Verify reviews/ is in .gitignore

   • If not, add it — review documents should not be committed

2. Create reviews/code/ directory if needed

3. Generate filename: {epoch_timestamp}-{short-description}.md

4. Write the review using this structure:

# Code Review: {Title}

**Date:** {YYYY-MM-DD}
**Reviewer:** Claude
**Branch:** {current branch name}
**Perspectives Applied:** {list of perspectives used}
**Files Reviewed:**
- `path/to/file.ext` (new|modified)
- ...

---

## Summary

{2-3 sentence overview: what was reviewed, overall assessment, most important finding.}

---

## Critical

### 1. {Issue Title}
**Perspective:** {which perspective found this}
**File:** [filename:line](path/to/file#L{line})

{Description of the issue and why it's critical.}

**Current:**
```{language}
{problematic code snippet}

Fix:

{corrected code snippet}

---

Warning

N. {Issue Title}

Perspective: {which perspective found this} File: filename:line

{Description and recommendation.}

---

Suggestion

N. {Issue Title}

Perspective: {which perspective found this} File: filename:line

{Description and suggestion.}

---

Positive Notes

• {Good patterns observed}
• {Well-implemented aspects}

---

Action Items

Priority	Item	File	Effort	Perspective
Critical	{desc}	{file}	Low/Med/High	{perspective}
Warning	{desc}	{file}	Low/Med/High	{perspective}

Omit any section that has no content. If there are no Critical findings, don't include the section.

### Phase 5: Present Summary

After writing the review:

1. **Report location** — tell user where the review was saved
2. **Summary:**
   - Perspectives applied and why
   - Count of Critical / Warning / Suggestion findings
   - Key issues needing attention
   - Overall assessment: ready to merge, needs work, or needs significant rework

---

## Output

Review document saved to `reviews/code/{epoch}-{description}.md`.