review-phase

If dispatched as a review subagent yourself, skip this skill — you are the worker, not the orchestrator. Just execute the review prompt you were given.

Review Phase

This is Phase 6 of marten-workflow. Its job: catch what the implementer missed, before the work merges.

Why This Phase Exists

The implementer is the worst reviewer of their own code — confirmation bias is near-total. Martin's global rules already mandate codex:adversarial-review at milestones, and "≥2 reviewers per area to triangulate". This skill chains that together with code-reviewer and security-review for full coverage.

Hard Rules (non-negotiable)

1. Run inside the topic's worktree, never on main or in the bare repo.
2. Reviewers see only the diff, not the whole repo state. Always pass --base main (or the actual parent ref) to codex:adversarial-review.
3. Dispatch parallel reviewers with disjoint focus areas — each prompt tells the reviewer to ignore the other reviewer's slice.
4. Verification before completion — confirm php artisan test, npm run build, or whatever the project's green-state check is, passes BEFORE running review. A failing test suite = back to Phase 5.
5. Fix only in-scope blockers. Out-of-scope findings → KNOWN_ISSUES.md.
6. Re-run reviewers after fixes until no remaining blockers.

Inputs

Before starting, confirm:

• Phase 5 (executing-plans) marked complete
• All tests pass locally (verification-before-completion skill applied)
• Working tree is clean (or only contains the intended diff)
• You're inside the worktree, not the main checkout

If any of those are false, fix first.

Step-by-step

1. Snapshot the diff scope

git status
git diff --stat main...HEAD
git log --oneline main...HEAD

Note the parent ref (usually main). Confirm the diff size — if it's huge (>500 lines), split into focus areas before dispatching reviewers.

2. Define focus areas

For diffs larger than ~200 LOC or touching multiple concerns, split into 2–3 non-overlapping focus areas. Examples:

• "auth + middleware + session handling" vs "UI components + Inertia props"
• "database schema + migration" vs "API controllers + validation"
• "core algorithm + tests" vs "wiring + config"

Each focus area gets one reviewer. Disjoint slices = no wasted attention.

3. Dispatch reviewers in parallel

Single tool message, multiple Agent calls:

3a. codex:adversarial-review (always, per global rule)

node ${CLAUDE_PLUGIN_ROOT_FOR_CODEX}/scripts/codex-companion.mjs \
  adversarial-review --background --base main \
  "<focus area 1 prompt>"

For 2 focus areas, run two adversarial-review invocations in parallel. Each prompt explicitly tells codex to ignore the other slice.

3b. code-reviewer subagent (always)

Dispatch via Agent tool, subagent_type: code-reviewer. Brief:

"Review the diff between main and HEAD in this worktree. Focus on: . Ignore: <other reviewer's slice>. Report severity-tagged findings only — no praise, no scope creep. Run any tests you need."

3c. security-review skill (when diff touches: auth, validation, file I/O, network, secrets, SQL, deserialization, file uploads, command exec)

Invoke via Skill tool with name security-review. This is a built-in skill, not a subagent.

3d. cto-agent (optional, for design judgment on >2-file refactors or new architectural patterns)

Dispatch via Agent tool, subagent_type: cto-agent. Brief:

"Review architectural decisions in this diff. Are the abstractions earning their keep? Is anything over-engineered or premature? Report only design-level concerns."

4. Reconcile findings

When all reviewers return, classify each finding:

Class	Action
Blocker, in-scope	Fix in this branch before merge
Blocker, out-of-scope	Log to KNOWN_ISSUES.md, file follow-up issue
Improvement, in-scope	Fix if cheap, otherwise defer + log
Improvement, out-of-scope	Log only
Disagreement between reviewers	Surface to user, let them decide
False positive	Note in summary, no action

5. Apply in-scope fixes

Use TDD where possible — failing test first, then fix. Keep commits small and focused.

6. Re-run reviewers after fixes

Dispatch another round of codex:adversarial-review (and others as needed) until no blockers remain. Do not skip this step — fixes can introduce new issues.

7. Write the review summary

Append to KNOWN_ISSUES.md (create if missing) at worktree root:

# Known Issues

## <Date> — Review of <feature/branch name>

### Out-of-scope blockers
- <issue>: <one-line description>. Tracked: <link / "no ticket yet">.

### Out-of-scope improvements
- <issue>: <one-line description>.

### Reviewer disagreements (resolved by user)
- <topic>: <reviewer A said X, B said Y, resolution>.

8. Hand off

Tell the user:

"Review phase complete. reviewers ran. In-scope blockers: <count, all fixed>. Out-of-scope: <count, logged in KNOWN_ISSUES.md>. Ready for Phase 7 (finishing-a-development-branch)."

Anti-patterns

• ❌ Reviewing your own code in the main thread (you wrote it, you'll miss it)
• ❌ Single reviewer ("codex caught nothing, I'm good") — always ≥2
• ❌ Letting reviewers see the full dirty tree instead of the diff
• ❌ Expanding scope to fix every finding the reviewers raise — that's a new branch, not this one
• ❌ Skipping re-review after fixes ("the fix is obvious") — fixes break things
• ❌ Performative agreement with reviewers without verification — apply superpowers:receiving-code-review rigor

Tool & permission reminders

• node ${CLAUDE_PLUGIN_ROOT_FOR_CODEX}/scripts/codex-companion.mjs adversarial-review must be allow-listed in the project's .claude/settings.local.json. One-time per repo.
• Worktree convention: <repo-parent>/.worktrees/<repo-name>-<topic>
• If .claude/settings.local.json permissions are needed in the worktree, copy from the main checkout (it's not in git).