description: "Code review with semantic diffs, expert routing, and auto-TodoWrite. Analyzes staged changes or specific files for bugs, security, performance, and style."

Review - AI Code Review

Perform a comprehensive code review on staged changes, specific files, or pull requests. Routes to expert agents based on file types, respects project conventions, and automatically creates TodoWrite tasks for critical issues.

Arguments

$ARGUMENTS

No args: Review staged changes (git diff --cached)
<file>: Review specific file
<directory>: Review all files in directory
--all: Review all uncommitted changes
--pr <number>: Review a GitHub PR
--focus <security|perf|types|tests|style>: Focus on specific area
--depth <quick|normal|thorough>: Review depth

Architecture

/review [target] [--focus] [--depth]
    │
    ├─→ Step 1: Determine Scope
    │     ├─ No args → git diff --cached (staged)
    │     ├─ --all → git diff HEAD (all uncommitted)
    │     ├─ File path → specific file diff
    │     └─ --pr N → gh pr diff N
    │
    ├─→ Step 2: Analyze Changes (parallel)
    │     ├─ delta for syntax-highlighted diff
    │     ├─ difft for semantic diff (structural)
    │     ├─ Categorize: logic, style, test, docs, config
    │     └─ Identify touched modules/components
    │
    ├─→ Step 3: Load Project Standards
    │     ├─ AGENTS.md, CLAUDE.md conventions
    │     ├─ .eslintrc, .prettierrc, pyproject.toml
    │     ├─ Detect test framework
    │     └─ Check CI config for existing linting
    │
    ├─→ Step 4: Route to Expert Reviewers
    │     ├─ TypeScript → typescript-expert
    │     ├─ React/JSX → react-expert
    │     ├─ Python → python-expert
    │     ├─ Vue → vue-expert
    │     ├─ SQL/migrations → postgres-expert
    │     ├─ Claude extensions → claude-architect
    │     └─ Multi-domain → parallel expert dispatch
    │
    ├─→ Step 5: Generate Review
    │     ├─ Severity: CRITICAL / WARNING / SUGGESTION / PRAISE
    │     ├─ Line-specific comments (file:line refs)
    │     ├─ Suggested fixes as diff blocks
    │     └─ Overall verdict: Ready to commit? Y/N
    │
    └─→ Step 6: Integration
          ├─ Auto-create TodoWrite for CRITICAL issues
          ├─ Link to /saveplan for tracking
          └─ Suggest follow-up: /test, /explain

Execution Steps

Step 1: Determine Scope

# Default: staged changes
git diff --cached --name-only

# Check if anything is staged
STAGED=$(git diff --cached --name-only | wc -l)
if [ "$STAGED" -eq 0 ]; then
    echo "No staged changes. Use --all for uncommitted or specify a file."
    git status --short
fi

For PR review:

gh pr diff $PR_NUMBER --patch

For specific file:

git diff HEAD -- "$FILE"

Step 2: Analyze Changes

Run semantic diff analysis (parallel where possible):

With difft (semantic):

command -v difft >/dev/null 2>&1 && git difftool --tool=difftastic --no-prompt HEAD~1 || git diff HEAD~1

With delta (syntax highlighting):

command -v delta >/dev/null 2>&1 && git diff --cached | delta || git diff --cached

Categorize changes:

# Get changed files
git diff --cached --name-only | while read file; do
    case "$file" in
        *.test.* | *.spec.*) echo "TEST: $file" ;;
        *.md | docs/*) echo "DOCS: $file" ;;
        *.json | *.yaml | *.toml) echo "CONFIG: $file" ;;
        *) echo "CODE: $file" ;;
    esac
done

Get diff statistics:

git diff --cached --stat

Step 3: Load Project Standards

Check for project conventions:

# Claude Code conventions
cat AGENTS.md 2>/dev/null | head -50
cat CLAUDE.md 2>/dev/null | head -50

# Linting configs
cat .eslintrc* 2>/dev/null | head -30
cat .prettierrc* 2>/dev/null
cat pyproject.toml 2>/dev/null | head -30

# Test framework detection
cat package.json 2>/dev/null | jq '.devDependencies | keys | map(select(test("jest|vitest|mocha|cypress|playwright")))' 2>/dev/null
cat pyproject.toml 2>/dev/null | grep -E "pytest|unittest" 2>/dev/null

Check CI for existing linting:

cat .github/workflows/*.yml 2>/dev/null | grep -E "eslint|prettier|pylint|ruff" | head -10

Step 4: Route to Expert Reviewers

Determine experts based on changed files:

File Pattern	Primary Expert	Secondary Expert
`*.ts`	typescript-expert	-
`*.tsx`	react-expert	typescript-expert
`*.vue`	vue-expert	typescript-expert
`*.py`	python-expert	sql-expert (if ORM)
`.sql`, `migrations/`	postgres-expert	-
`agents/.md`, `skills/`, `commands/*`	claude-architect	-
`.test.`, `.spec.`	cypress-expert	(framework expert)
`wrangler.toml`, `workers/*`	wrangler-expert	cloudflare-expert
`.sh`, `.bash`	bash-expert	-

Multi-domain changes: If files span multiple domains, dispatch experts in parallel via Task tool.

Invoke via Task tool:

Task tool with subagent_type: "[detected]-expert"
Prompt includes:
  - Diff content
  - Project conventions from AGENTS.md
  - Linting config summaries
  - Requested focus area
  - Request for structured review output

Step 5: Generate Review

The expert produces a structured review:

# Code Review: [scope description]

## Summary

| Metric | Value |
|--------|-------|
| Files reviewed | N |
| Lines changed | +X / -Y |
| Issues found | N (X critical, Y warnings) |

## Verdict

**Ready to commit?** Yes / No

[1-2 sentence summary of overall quality]

---

## Critical Issues

### `src/auth/login.ts:42`

**Issue:** SQL injection vulnerability in user input handling

**Risk:** Attacker can execute arbitrary SQL queries

**Fix:**
```diff
- const query = `SELECT * FROM users WHERE id = ${userId}`;
+ const query = `SELECT * FROM users WHERE id = $1`;
+ const result = await db.query(query, [userId]);

Warnings

`src/components/Form.tsx:89`

Issue: Missing dependency in useEffect

Suggestion: Add userId to dependency array or use useCallback

- useEffect(() => { fetchUser(userId) }, []);
+ useEffect(() => { fetchUser(userId) }, [userId]);

Suggestions

`src/utils/helpers.ts:15`

Suggestion: Consider using optional chaining

- const name = user && user.profile && user.profile.name;
+ const name = user?.profile?.name;

Praise

`src/services/api.ts:78`

Good pattern: Proper error boundary with typed error handling. This is exactly the pattern we want to follow.

Files Reviewed

File	Changes	Issues
`src/auth/login.ts`	+42/-8	1 critical
`src/components/Form.tsx`	+89/-23	1 warning
`src/utils/helpers.ts`	+15/-3	1 suggestion

Follow-up

Run /test src/auth/ to verify security fix
Run /explain src/auth/login.ts for deeper understanding
Use /saveplan to track these issues ```

Step 6: Integration

Auto-create TodoWrite tasks for CRITICAL issues:

For each CRITICAL issue found, automatically add to TodoWrite:

TodoWrite:
  - content: "Fix: SQL injection in login.ts:42"
    status: "pending"
    activeForm: "Fixing SQL injection in login.ts:42"

Link to session management:

Issues have been added to your task list.
Run /saveplan to persist before ending session.

Severity System

Level	Icon	Meaning	Action	Auto-Todo?
CRITICAL	:red_circle:	Security bug, data loss risk, crashes	Must fix before merge	Yes
WARNING	:yellow_circle:	Logic issues, performance problems	Should address	No
SUGGESTION	:blue_circle:	Style, minor improvements	Optional	No
PRAISE	:star:	Good patterns worth noting	Recognition	No

Focus Modes

Mode	What It Checks
`--security`	OWASP top 10, secrets in code, injection, auth issues
`--perf`	N+1 queries, unnecessary re-renders, complexity, memory
`--types`	Type safety, `any` usage, generics, null handling
`--tests`	Coverage gaps, test quality, mocking patterns
`--style`	Naming, organization, dead code, comments
(default)	All of the above

Security Focus Example

/review --security

Checks for:

Hardcoded secrets, API keys
SQL/NoSQL injection
XSS vulnerabilities
Insecure dependencies
Auth/authz issues
CORS misconfigurations

Performance Focus Example

/review --perf

Checks for:

N+1 database queries
Unnecessary re-renders (React)
Memory leaks
Blocking operations in async code
Unoptimized algorithms

Depth Modes

Mode	Behavior
`--quick`	Surface-level scan, obvious issues only
`--normal`	Standard review, all severity levels (default)
`--thorough`	Deep analysis, traces data flow, checks edge cases

CLI Tool Integration

Tool	Purpose	Fallback
`delta`	Syntax-highlighted diffs	`git diff`
`difft`	Semantic/structural diffs	`git diff`
`gh`	GitHub PR operations	Manual diff
`rg`	Search for patterns	Grep tool
`jq`	Parse JSON configs	Read manually

Graceful degradation:

command -v delta >/dev/null 2>&1 && git diff --cached | delta || git diff --cached

Usage Examples

# Review staged changes (default)
/review

# Review all uncommitted changes
/review --all

# Review specific file
/review src/auth/login.ts

# Review a directory
/review src/components/

# Review a GitHub PR
/review --pr 123

# Security-focused review
/review --security

# Performance-focused review
/review --perf

# Quick scan before committing
/review --quick

# Thorough review for important changes
/review --thorough

# Combined: thorough security review of PR
/review --pr 456 --security --thorough

Framework-Specific Checks

React/Next.js

Hook rules violations
Missing useEffect dependencies
Key prop issues in lists
Server/client component boundaries
Hydration mismatches

TypeScript

any type abuse
Missing type annotations on exports
Incorrect generic constraints
Type assertion overuse (as)
Null/undefined handling

Python

Mutable default arguments
Bare except: clauses
Resource leaks (files, connections)
SQL string formatting
Type hint inconsistencies

Vue

Reactivity gotchas
Missing v-key in v-for
Props mutation
Composition API anti-patterns

SQL/Database

SQL injection risks
N+1 query patterns
Missing indexes
Transaction handling
Migration safety

Integration

Command	Relationship
`/explain`	Deep dive into flagged code
`/test`	Generate tests for issues found
`/saveplan`	Persist review findings to session state
`/plan`	Add review findings to project plan

Workflow Examples

Pre-Commit Review

git add .
/review
# Fix issues...
git commit -m "feat: add user auth"

PR Review Workflow

/review --pr 123 --thorough
# Creates TodoWrite tasks for critical issues
# Fix issues...
/saveplan "Addressed review findings"

Security Audit

/review src/ --security --thorough
# Comprehensive security scan of entire directory

Notes

Reviews are suggestions, not absolute rules
Context matters - some "issues" may be intentional
CRITICAL issues are auto-added to TodoWrite
Use /saveplan to persist review tasks across sessions
Expert agents provide framework-specific insights
Respects project conventions from AGENTS.md

review.md 12 KB History Raw