Review

---
name: review
description: "Reviews code changes for bugs with P0-P2 prioritized feedback. Uses parallel subagents for thorough analysis, then creates fix plans. Use when reviewing code, finding bugs, checking quality, or before merging. Use /review fix to implement fixes."
argument-hint: "[staged | branch] | fix [P0 | P0-P1 | all]"
model: "opus"
---

**Arguments:** $ARGUMENTS

| Command | Behavior |
|---------|----------|
| `/review` | Review branch diff, synthesize findings, create fix plan |
| `/review staged` | Review staged changes only |
| `/review fix` | Implement all fixes from saved plan |
| `/review fix P0` | Implement only P0 (critical) fixes |
| `/review fix P0-P1` | Implement P0 and P1 fixes |

| Scope | Git Command |
|-------|-------------|
| `branch` (default) | `git diff main...HEAD` |
| `staged` | `git diff --cached` |

---

## Review Mode

### Step 1: Categorize Changes

Get the diff and categorize files by change type:

**Architectural changes** → assign to `architect-reviewer`:
- API routes, endpoints, controllers
- Database schemas, migrations
- Service interfaces, dependency injection
- Configuration files (docker, CI/CD)
- Directory structure changes

**Implementation changes** → assign to `senior-code-reviewer`:
- UI components, styling
- Business logic within existing patterns
- Bug fixes, refactoring
- Test files
- Utility functions

If a file fits both categories, assign to both reviewers.

### Step 2: Launch Review Subagents

**Scale based on change size:**
- 1-4 files: 1 subagent
- 5-10 files: 2-3 subagents grouped by directory/component
- 10+ files: 3-5 subagents grouped by directory/component

**Handoff to reviewer subagents:**
- File list to review
- Diff command: `git diff main...HEAD -- <files>` (or `--cached` for staged)
- Scope context (branch or staged)

Subagents return prioritized findings (P0-P2) in consistent format with Files, Problem, Fix, and Done when.

Wait for all subagents to complete.

### Step 3: Synthesize Findings

1. **Collect** all findings from subagents
2. **Deduplicate** overlapping findings
3. **Sort** by priority (P0 first)
4. **Present** findings table for review:

```markdown
## Code Review Findings

| P | Problem | Fix Approach | Files | Done When |
|---|---------|--------------|-------|-----------|
| P0 | Null pointer in user lookup | Add early return with 404 | `users.ts:47` | Returns 404 for missing user |
| P1 | Race condition in cache | Use mutex lock | `cache.ts:23` | Concurrent requests don't corrupt |
| ... | ... | ... | ... | ... |

**Verdict: CORRECT | NEEDS FIXES**
```

**If no findings:** Report "No issues found" and stop.

### Step 4: Validate Findings

Skip this step if there are no findings (verdict is already CORRECT).

Launch `false-positive-validator` with:
- The full findings list from Step 3
- Scope context (branch or staged)
- Diff command used

**Process results:**
1. **Replace** findings list with validated results (KEPT + DOWNGRADED findings only)
2. **Re-sort** by priority (P0 first)
3. **Append** a collapsed details section showing what was removed or changed:

```markdown
<details>
<summary>Validation: {N} removed, {M} downgraded</summary>

| Finding | Verdict | Reason |
|---------|---------|--------|
| [P1] Title | FALSE POSITIVE | Already handled — `file.ts:32` has null check |
| [P0 → P2] Title | DOWNGRADED | Context negates severity — `api.ts:15` validates input |

</details>
```

4. **If all findings removed** → verdict becomes CORRECT, report "No issues found after validation" and stop
5. Otherwise proceed to Step 5

### Step 5: Resolve Ambiguous Fixes

**If any fix requires a decision** (contains "Either...OR", "Option A/B", or similar patterns), use `AskUserQuestion` to interview the user:

```
[P0] Plugin discovery limited to 3 hardcoded paths

The fix has multiple options:
A) Restore two-pass file fetching (more complete, adds complexity)
B) Remove dead countCommands/countSkills functions (simpler, less data)

Which approach?
```

**Process multiple ambiguous fixes** in a single interview when possible:
- Group related decisions together
- Show context for each choice
- Update fixes with chosen approaches

**If no ambiguous fixes**, skip to Step 6.

### Step 6: Approve Fix Plan

**Ask for approval** using `AskUserQuestion`:
- "Approve and save plan"
- "Request changes" — revise based on feedback
- "Open in editor" — save to `.otto/reviews/fix-plan-draft.md` for editing

**On approval**, write fix plan to `.otto/reviews/fix-plan.json`:
```json
{
  "version": 1,
  "created": "{timestamp}",
  "scope": "{scope}",
  "branch": "{branch}",
  "commit_sha": "{HEAD}",
  "summary": { "p0": 0, "p1": 0, "p2": 0, "p3": 0 },
  "verdict": "NEEDS FIXES",
  "fixes": [
    {
      "id": "f1",
      "priority": "P0",
      "title": "Null pointer dereference in user lookup",
      "problem": "user.profile accessed without null check",
      "fix": "Add early return with 404 when user is null",
      "files": [
        { "path": "src/auth/users.ts", "line": 47, "role": "primary" },
        { "path": "src/auth/users.test.ts", "role": "add test" }
      ],
      "done_when": "Returns 404 for missing user; test covers case",
      "status": "pending",
      "depends_on": []
    }
  ]
}
```

Report: `Fix plan saved. Run /review fix to implement.`

---

## Fix Mode

### Step 1: Load and Filter

1. Check `.otto/reviews/fix-plan.json` exists
   - If missing or stale (code changed): run `/review` first
2. Filter by priority argument:
   - `fix` or `fix all`: P0-P2
   - `fix P0`: P0 only
   - `fix P0-P1`: P0 and P1
3. If no matching fixes: report "No {priority} issues to fix"

### Step 2: Implement in Batches

**Select unblocked fixes** — where all `depends_on` are done.

**Scale subagents:**
- 1-3 fixes: 1 subagent
- 4-7 fixes: 2 subagents
- 8+ fixes: 3 subagents (max)

Prefer fewer subagents with multiple fixes each. Single-file fixes in the same directory should always share a subagent.

**Each subagent receives:**
- Fix details (priority, problem, fix approach, files, done_when)
- **The current contents of each file to modify** (read files before launching subagents to avoid per-subagent read rounds)
- Instructions: implement fix, run `git add {files}`, mark status done in fix-plan.json

**After each batch:** re-evaluate unblocked fixes, launch next batch, repeat until done.

**Verify:** Run type check and linter after all fixes are applied. If errors relate to a fix, correct them directly (do not re-launch subagents). Report results.

### Step 3: Commit and Cleanup

1. Create commit:
   ```
   Fix review issues P{highest}-P{lowest}

   - [P{N}] Brief description
   - [P{N}] Brief description
   ```
2. Remove `.otto/reviews/fix-plan.json`
3. Report results:
   ```
   ## Fix Results
   | Issue | Status |
   |-------|--------|
   | [P0] Null reference | ✓ Fixed |
   | [P1] Race condition | ✓ Fixed |

   Commit: {hash}
   ```