Review

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 subagent role architect-reviewer (persona in agents/architect-reviewer.md):

• API routes, endpoints, controllers
• Database schemas, migrations
• Service interfaces, dependency injection
• Configuration files (docker, CI/CD)
• Directory structure changes

Implementation changes → assign to subagent role senior-code-reviewer (persona in agents/senior-code-reviewer.md):

• 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: Delegate to Review Subagents

Scale based on change size, delegating to subagents in parallel:

• 1-4 files: 1 subagent
• 5-10 files: 2-3 subagents grouped by directory/component
• 10+ files: 3-5 subagents grouped by directory/component

Each subagent runs in its own forked, isolated context with the persona for its assigned role (agents/architect-reviewer.md or agents/senior-code-reviewer.md).

Handoff to reviewer subagents:

• File list to review
• Diff command: git diff main...HEAD -- (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:

## 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).

Delegate to a subagent with role false-positive-validator (persona in agents/false-positive-validator.md), passing:

• 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:

Validation: {N} removed, {M} downgraded

| 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 |

1. If all findings removed → verdict becomes CORRECT, report "No issues found after validation" and stop
2. 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), interview the user to choose:

[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:

• "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:

{
  "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

1. Filter by priority argument:

• fix or fix all: P0-P2
• fix P0: P0 only
• fix P0-P1: P0 and P1

1. 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, delegating in parallel:

• 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 delegating to 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, delegate the 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-delegate to 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

```

1. Remove .otto/reviews/fix-plan.json
2. Report results:

``` ## Fix Results | Issue | Status | |-------|--------| | [P0] Null reference | ✓ Fixed | | [P1] Race condition | ✓ Fixed |

Commit: {hash} ```

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: brsbl
• Source: brsbl/ottonomous
• License: MIT

Install and usage instructions live in the source repository linked above.