Review Plan

---
name: review-plan
description: Validate an implementation plan by checking for gaps, ambiguity, incorrect assumptions, and missing dependencies. Use after creating a plan and before execution.
argument-hint: "[focus areas for review]"
context: fork
agent: reviewer
metadata:
  author: @ivy
---

# Review Plan: Validate Before Executing

You are reviewing an implementation plan. Your job is to find problems before they waste execution time. Be direct about issues — a false positive costs a re-read, a missed problem costs a rework cycle.

## Arguments

```
$ARGUMENTS
```

## Instructions

### 1. Find the Plan

Read the active plan file. Check these locations in order:

- `~/.claude/plans/` — most recent `.md` file
- Plan content in recent conversation context

If no plan is found, report this and stop.

### 2. Cross-Reference with Codebase

For every concrete claim the plan makes, verify it:

| Claim type              | Verification                                                           |
| ----------------------- | ---------------------------------------------------------------------- |
| "Modify `src/foo.ts`"   | Does `src/foo.ts` exist?                                               |
| "Call `functionName()`" | Does `functionName` exist? Is the signature correct?                   |
| "Import from `package`" | Is `package` in dependencies?                                          |
| "Tests are in `test/`"  | Does the test directory exist? What patterns do existing tests follow? |
| "Convention is X"       | Does CLAUDE.md or the codebase confirm this?                           |

Use `Glob`, `Grep`, and `Read` to verify. Don't trust the plan's claims about the codebase — check them.

### 3. Check Task Graph Integrity

Review the dependency structure:

- **Missing dependencies**: Does Task C use output from Task A without declaring `blockedBy: [A]`?
- **Circular dependencies**: Are there cycles that would deadlock execution?
- **Over-serialization**: Are tasks marked sequential that could actually run in parallel?
- **Under-serialization**: Are tasks marked parallel that actually depend on each other (e.g., both touch the same file)?
- **Orphan tasks**: Are there tasks with no downstream consumer? (Might be intentional, might be a gap.)

### 4. Assess Instruction Clarity

For each task, ask: could an agent execute this without further clarification?

Flag as ambiguous:

- "Update the config" — which config? What change?
- "Fix the tests" — which tests? What's wrong?
- "Follow the existing pattern" — which pattern? Where is it?

Good task descriptions name specific files, functions, and expected behavior.

### 5. Check for Missing Work

Common gaps:

- Tests not included for new functionality
- Missing error handling for new code paths
- No commit strategy defined
- No verification step after changes
- Edge cases mentioned in the issue but not addressed in tasks
- Platform-specific behavior not handled (check for `.tmpl` files, OS conditionals)

### 6. Report Findings

Categorize findings by severity:

**Blocking** — must fix before execution:

- Wrong file paths or function names
- Missing critical dependencies between tasks
- Incorrect API usage or assumptions about tool behavior
- Tasks that would fail because prerequisites don't exist

**Warning** — should address but can proceed:

- Vague task descriptions that might cause agent confusion
- Untested assumptions that are probably correct but not verified
- Missing test tasks for new code
- Suboptimal parallelization (could be faster)

**Note** — improvements, not blockers:

- Style suggestions
- Alternative approaches worth considering
- Minor optimizations

If `$ARGUMENTS` specifies focus areas, weight your review toward those concerns — but check task
graph integrity either way, since a dependency error invalidates the plan regardless of what the
review was asked to focus on.

### 7. Verdict

End with a clear verdict:

- **Approve** — no blocking issues, proceed to execution
- **Revise** — blocking issues found, list what needs to change before proceeding