---

name: code-review description: Code review methodology. Use when reviewing code locally or preparing for a PR review.

Code Review Skill

Multi-perspective code review using parallel subagent dispatch for comprehensive analysis.

Reference: See reference/roles/ for reviewer personas, reference/report.md for YAML schemas, reference/playbook.md for edge case handling.

---

When to Use

• Reviewing code changes locally before commit
• Preparing review feedback for a PR
• Final review of a spec implementation
• Analyzing code quality across multiple dimensions

---

Command

Copy/code.review [target]
/code.review --spec <name>
/code.review --rev <ref>
/code.review --path <path>
/code.review --diff

Target types (auto-detected by default):

• Spec name → Final review of spec implementation
• Git rev → Review changes in commit(s)
• Git range → Review changes between refs
• Path → Review file or directory
• No argument → Review staged/unstaged changes

Disambiguation flags (optional):

• --spec → Force spec mode (e.g., spec named "main")
• --rev → Force git rev mode (e.g., path named "HEAD")
• --path → Force path mode (e.g., directory named "v1.0")
• --diff → Force diff mode (staged/unstaged changes)

---

Workflow

Step 1: Detect Input Type

If flag provided, use it directly:

Copy--spec auth-system  → Spec mode (no detection)
--rev main          → Git rev mode (no detection)
--path ./main       → Path mode (no detection)

Otherwise, auto-detect:

CopyInput                    | Detection                           | Mode
-------------------------|-------------------------------------|-------------
auth-system              | ./specs/active/auth-system/ exists  | Spec (final)
HEAD~3                   | Valid git rev                       | Git rev
main..feature            | Valid git range                     | Git range
abc123f                  | Valid commit SHA                    | Git rev
src/auth/                | Path exists                         | Path
(no argument)            | -                                   | Diff

Auto-detection priority:

1. Check for spec: test -d ./specs/active/{arg}/
   • If exists → Spec mode (final review)
2. Check for git rev: git rev-parse --verify {arg} 2>/dev/null
   • If valid → Git rev mode
3. Check for git range: contains .. and valid refs
   • If valid → Git range mode
4. Check for path: test -e {arg}
   • If exists → Path mode
5. No argument:
   • Check git diff --cached → staged changes
   • Check git diff → unstaged changes
   • If neither → ask user

Ambiguity examples:

Copy# "main" could be spec, branch, or directory
/code.review main           # Auto-detect (spec first, then git, then path)
/code.review --spec main    # Force: spec named "main"
/code.review --rev main     # Force: git branch "main"
/code.review --path main    # Force: directory named "main"

Step 2: Load Review Context

Spec mode:

CopyRead (in parallel):
  ./specs/active/<spec>/spec.md        # Requirements
  ./specs/active/<spec>/tasks.yaml     # Task definitions
  ./specs/active/<spec>/review.yaml    # Batch review history
  ./specs/active/<spec>/validation.yaml # Review config + reviewers

Git rev/range mode:

Copygit show <rev>              # Single commit
git diff <range>            # Range (e.g., main..feature)
git log --oneline <range>   # Commit messages for context

Path mode:

Copy# Read file(s) at path
# If directory, find changed files or all files

Diff mode:

Copygit diff --cached           # Staged changes (preferred)
git diff                    # Unstaged changes (fallback)

Step 3: Select Reviewers

Spec mode: Use reviewers from validation.yaml (no prompt):

Copyreview_config:
  reviewers:
    - type: claude
      model: opus
    - type: opencode
      model: openai/gpt-5.2-codex

Other modes: Use AskUserQuestion:

Question 1: Select reviewers:

CopyHeader: Reviewers
Question: Which reviewers should analyze this code?
multiSelect: true
Options:
- claude-opus: Claude Opus - native subagent, context-aware, codebase access
- claude-sonnet: Claude Sonnet - faster native review
- openai-gpt5.2-codex: OpenAI GPT-5.2 Codex - code-specialized (Recommended)
- openai-gpt5.2-pro: OpenAI GPT-5.2 Pro - extended capabilities
- gemini-3-pro: Google Gemini 3 Pro - advanced reasoning

Default selection: claude-opus, openai-gpt5.2-codex

Question 2: Select reasoning effort (if OpenCode reviewers selected):

CopyHeader: Reasoning
Question: What reasoning effort level for OpenCode reviewers?
multiSelect: false
Options:
- low: Quick responses, minimal deliberation
- medium: Balanced reasoning (Recommended)
- high: Deep analysis, thorough deliberation
- xhigh: Maximum reasoning (GPT-5.2 only)

Default: medium

Model mapping to commands:

• claude-opus → Task tool with model: "opus"
• openai-gpt5.2-codex → opencode run --model "openai/gpt-5.2-codex" --variant {reasoning}-medium
• openai-gpt5.2-pro → opencode run --model "openai/gpt-5.2" --variant {reasoning}-medium
• gemini-3-pro → opencode run --model "google/gemini-3-pro-preview" --variant {reasoning}-medium

Step 4: Dispatch Reviewers in Parallel

CRITICAL: Dispatch all reviewers in the same message for true parallelism.

Dispatch by Type:

Claude reviewers (Task tool):

CopyTask(
  subagent_type="general-purpose",
  model="opus",  # or "sonnet"
  prompt=review_prompt
)

OpenCode reviewers (Bash tool, background):

Copytimeout 1200 opencode run --model "{MODEL_PATH}" --variant {reasoning}-medium "{review_prompt}"

Examples (with high reasoning):

• opencode run --model "openai/gpt-5.2-codex" --variant high-medium "{prompt}"
• opencode run --model "openai/gpt-5.2" --variant high-medium "{prompt}"
• opencode run --model "google/gemini-3-pro-preview" --variant high-medium "{prompt}"

Review Prompt (standard):

CopyYou are reviewing code for quality, correctness, and maintainability.

## Code to Review
[Include diff or file contents]

## Context
[Git commit message, PR description, or spec requirements]

## Review Focus
Evaluate against these gates:

1. **Correctness** - Logic errors, edge cases, error handling, type safety
2. **Style** - Naming, formatting, idioms, readability
3. **Performance** - Efficiency, data structures, unnecessary work
4. **Security** - Input validation, secrets, injection risks
5. **Architecture** - Design patterns, coupling, separation of concerns

## Output Format
[Standard reviewer_report YAML - see reference/report.md]

Review Prompt (spec mode - final review):

CopyYou are performing a FINAL REVIEW of a complete spec implementation.

## Spec Requirements
[Include spec.md content]

## Tasks Implemented
[Include tasks.yaml]

## Batch Review History
[Summarize from review.yaml]

## Deferred Issues
[List medium-severity issues from batch reviews]

## Review Focus
1. **Spec Compliance** - All requirements met? Acceptance criteria satisfied?
2. **Gates** - Correctness, Style, Performance, Security, Architecture
3. **Deferred Issues** - Address or document remaining issues
4. **Integration** - Components work together? No regressions?
5. **Test Coverage** - All behaviors tested?

## Output Format
[Final review YAML - see reference/report.md]

Step 5: Synthesize Reviews

After all reviewers complete:

1. Parse reports - Extract YAML from all outputs
2. Merge issues:
   • Deduplicate by location + description similarity
   • Combine issues flagged by multiple reviewers (higher confidence)
   • Note which reviewer(s) found each issue
3. Aggregate gates:
   • Gate fails if ANY reviewer fails it
   • Record which reviewer(s) failed each gate
4. Prioritize by severity:
   • Critical → High → Medium
   • Within severity, group by gate

Step 6: Write Review Output

Spec mode → ./specs/active/<spec>/review.yaml:

Copyfinal_review:
  status: completed
  timestamp: <ISO_TIMESTAMP>
  reviewers: [...]
  gates: { correctness: pass, style: pass, ... }
  spec_compliance:
    all_tasks_complete: true
    acceptance_criteria_met: true
    edge_cases_handled: true
  issues: [...]
  strengths: [...]
  recommendation: ready_to_merge | changes_requested

readiness:
  all_batches_reviewed: true
  critical_issues_resolved: true
  high_issues_resolved: true
  final_review_passed: true
  tests_passing: true

Other modes → ~/.claude/reviews/<generated-name>.md (ephemeral):

Copy# Generate review name based on input type
mkdir -p ~/.claude/reviews

# Git rev:    review-abc123f-2026-01-22T14-30.md
# Git range:  review-main..feature-2026-01-22T14-30.md
# Path:       review-src-auth-2026-01-22T14-30.md
# Diff:       review-staged-2026-01-22T14-30.md

Ephemeral review format (Markdown):

Copy# Code Review: <target>

**Date:** 2026-01-22T14:30:00Z
**Reviewers:** claude-opus, opencode-codex
**Target:** HEAD~3 | main..feature | src/auth/ | staged changes

## Gate Summary

| Gate         | Status | Claude | Codex  |
|--------------|--------|--------|--------|
| Correctness  | PASS   | pass   | pass   |
| Style        | PASS   | pass   | pass   |
| Performance  | PASS   | pass   | pass   |
| Security     | FAIL   | fail   | pass   |
| Architecture | PASS   | pass   | pass   |

## Issues

### Critical
- **[C1]** SQL injection in user input (Security)
  - Location: src/db/query.py:45
  - Found by: claude-opus
  - Suggestion: Use parameterized queries

### High
...

### Medium
...

## Strengths
- Clean separation of concerns
- Good error messages

## Recommendation
Address critical issues before proceeding

Reviews are stored ephemerally like Claude's internal plans - useful for reference but not committed to the repo.

Step 7: Present Review

Gate Summary Table:

Copy| Gate         | Status | Claude | Codex  |
|--------------|--------|--------|--------|
| Correctness  | PASS   | pass   | pass   |
| Style        | PASS   | pass   | pass   |
| Performance  | PASS   | pass   | pass   |
| Security     | FAIL   | fail   | pass   |
| Architecture | PASS   | pass   | pass   |

Issues by Severity:

Copy## Critical (must fix)
- [C1] SQL injection in user input (Security) at src/db/query.py:45
  Found by: claude-opus
  Suggestion: Use parameterized queries

## High (should fix)
...

## Medium (consider)
...

Spec mode additional output:

Copy### Spec Compliance
- All tasks complete: ✓
- Acceptance criteria met: ✓
- Edge cases handled: ✓

### Deferred Issues
- Resolved: 3
- Remaining: 0

Step 8: Recommend Action

All gates pass:

CopyReview complete. All gates passed.
Recommendation: Ready to commit/merge

Issues found:

CopyReview complete. 1 gate failed.
Critical: 1, High: 0, Medium: 2
Recommendation: Address critical issues before proceeding

Spec mode (all pass):

CopyFinal review complete: auth-system
Recommendation: Ready to merge ✓
Next: Create PR with /pr.create or merge directly

---

Gates

---

Issue Areas

---

Examples

Copy# Auto-detected (most common)
/code.review auth-system      # Spec → final review
/code.review HEAD~3           # Git rev → last 3 commits
/code.review main..feature    # Git range → branch diff
/code.review abc123f          # Git rev → specific commit
/code.review src/auth/        # Path → directory
/code.review                  # Diff → staged/unstaged

# Disambiguation flags (when names collide)
/code.review --spec main      # Spec named "main" (not git branch)
/code.review --rev main       # Git branch "main" (not spec/path)
/code.review --path HEAD      # Directory named "HEAD" (not git ref)
/code.review --rev v1.0       # Git tag "v1.0" (not path)
/code.review --diff           # Staged/unstaged changes explicitly

---

Review Storage

Naming convention for ephemeral reviews:

• review-<sha>-<timestamp>.md - Git rev
• review-<from>..<to>-<timestamp>.md - Git range
• review-<path-slug>-<timestamp>.md - Path
• review-staged-<timestamp>.md - Staged changes

---

Edge Cases

Spec not found:

• List available specs in ./specs/active/
• Suggest closest match if typo likely

Git rev invalid:

• Report error, suggest valid refs
• List recent commits for reference

OpenCode timeout (> 20 minutes):

• Continue with completed reviews
• Note: "[Reviewer] timed out, partial results"

No code to review:

• List recent changed files
• Ask user to specify target

---

Integration

Command: /code.review [target]

Related skills:

• code-implement - Language-specific patterns to check against
• pr-review - GitHub PR workflow (uses this for methodology)
• code-debug - Root cause analysis when issues found
• task-dispatch - Batch reviews during implementation (Phase C)

---

Reference

• reference/roles/claude-reviewer.md - Claude reviewer persona
• reference/roles/opencode-reviewer.md - OpenCode reviewer persona
• reference/report.md - YAML report schemas
• reference/playbook.md - Edge case handling
• reference/checklist.md - Review checklist