plan-review

Plan Review Skill

Purpose

When the user runs /plan-review {plan-file-path}, start the "adversarial plan iteration" workflow:

1. I (Claude Code) ask Codex to perform a critical review of the specified plan.
2. I read the review produced by Codex and evaluate whether its suggestions are sound.
3. I revise the plan based on valid suggestions and write changes back to the original plan file.
4. If the review status is NEEDS_REVISION, I automatically ask Codex to review again.
5. Repeat until consensus is reached as MOSTLY_GOOD or APPROVED.

Usage

/plan-review plans/my-feature-plan.md

Session Reuse

After each Codex invocation, extract session_id=xxx from the script output and save it as the session ID for the current task. In later Codex calls for the same task, pass --session <id> to reuse context so Codex remembers prior review history and can stay consistent across multiple rounds.

My Workflow (Claude Code)

Step 1: Determine the Review File

Derive the review file path from the plan file name:

• plans/auth-refactor.md → reviews/auth-refactor-review.md
• Rule: reviews/{plan-file-name-without-.md}-review.md

If the review file already exists, this is not the first round, so Codex must track the resolution status of issues from the previous round.

Step 2: Ask Codex to Review the Plan

Use the /codex skill and give Codex the following instruction:

Read the contents of {plan-file-path} and review it critically as an independent third-party reviewer.

Requirements:
- Raise at least 10 concrete and actionable improvement points
- Each issue must include: issue description + exact location/reference in the plan + improvement suggestion
- Use severity levels: Critical > High > Medium > Low > Suggestion
- If {review-file-path} already exists, read it first and track the resolution status of previous issues in the new round

Analysis dimensions, choosing the relevant ones based on the plan type:
- Architectural soundness: overdesign vs underdesign, module boundaries, single responsibility
- Technology choices: rationale, alternatives, compatibility with the existing project stack
- Completeness: missing scenarios, overlooked edge cases, dependency and impact scope
- Feasibility: implementation complexity, performance risks, migration and compatibility concerns
- Engineering quality: whether it follows the Code Quality Hard Limits in `CLAUDE.md`
- User experience: interaction flow, error/loading states, i18n when relevant
- Security: authentication, authorization, data validation when relevant

Append the current review round to {review-file-path}, creating the file if it does not exist.
Separate rounds with `---` and append new rounds at the end of the file. Use this format:

---

## Round {N} — {YYYY-MM-DD}

### Overall Assessment
{2-3 sentence overall assessment}
**Rating**: {X}/10

### Previous Round Tracking (R2+ only)
| # | Issue | Status | Notes |
|---|-------|--------|-------|

### Issues
#### Issue 1 ({severity}): {title}
**Location**: {location in the plan}
{issue description}
**Suggestion**: {improvement suggestion}
... (at least 10 issues)

### Positive Aspects
- ...

### Summary
{Top 3 key issues}
**Consensus Status**: NEEDS_REVISION / MOSTLY_GOOD / APPROVED

Key principle: be a critical reviewer, not a yes-man. Every issue must be specific enough that someone knows how to revise the plan.