Plan Review
Load this skill when reviewing implementation plans (not code).
TL;DR
Systematic plan review focused on 3 quality categories: Citation Quality, Completeness, and Actionability. Structure is pre-validated by plan_save—focus on whether the plan provides actionable implementation guidance.
When to Use This Skill
- When reviewing implementation plans before execution
- When auditing plan quality after creation
- When verifying plans meet documentation standards
- As part of the plan validation workflow
Plan Review Checklist
1. Structure (Pre-validated)
Note: Saved plans are structurally validated by plan_save before storage. Format compliance (YAML frontmatter, status markers, CURRENT marker, numbering) is guaranteed. Focus your review on the quality aspects below.2. Citation Quality
| Requirement | Check |
|---|---|
| Decisions reference sources | ref:delegation-id format used |
| No unsubstantiated claims | Architectural decisions cite research |
| Research phases show refs | Completed research tasks include citations |
| Citations are verifiable | IDs match actual delegation outputs |
Red Flags:
- Decisions table with empty or
-in Source column - Claims like "industry standard" or "best practice" without citation
- Research tasks marked complete without
→ ref:id
3. Completeness
| Requirement | Check |
|---|---|
| Goal is specific | Measurable outcome, not vague intent |
| Phases are logical | Sequential, with clear progression |
| Edge cases considered | Error handling, failure modes addressed |
| Notes section present | Key decisions and observations documented |
| Context & Decisions table | Captures architectural choices with rationale |
Goal Quality Examples:
- ❌ "Improve authentication" (vague)
- ❌ "Make it better" (unmeasurable)
- ✅ "Add JWT authentication with refresh token support" (specific)
- ✅ "Migrate user table to PostgreSQL with zero downtime" (measurable)
4. Actionability
| Requirement | Check |
|---|---|
| Tasks are specific | Clear what file/component is affected |
| No ambiguous tasks | Avoids "investigate" or "figure out" without scope |
| Dependencies clear | Sequential tasks show logical order |
| Implementation path obvious | Developer can start without clarification |
Actionability Examples:
- ❌ "Set up the backend" (too vague)
- ❌ "Make it work" (no implementation path)
- ✅ "Create
src/auth/jwt.tswith sign/verify functions" (specific file) - ✅ "Add bcrypt password hashing to
UserService.create()" (clear scope)
Severity Classification
| Severity | Icon | Criteria | Action Required |
|---|---|---|---|
| Critical | 🔴 | Missing citations for key decisions, no clear goal, unactionable tasks | Must fix before execution |
| Major | 🟠 | Vague tasks, incomplete phases, missing edge case handling | Should fix |
| Minor | 🟡 | Missing notes, unclear dependencies, incomplete rationale | Nice to fix |
| Nitpick | 🟢 | Style preferences, wording suggestions | Optional |
Output Format
Structure your plan review as:
## Plan Review
### Files Reviewed
- `PLAN.md` (or plan content from `plan_read`)
### Overall Assessment
APPROVE | REQUEST_CHANGES | NEEDS_DISCUSSION
### Summary
2-3 sentence overview of plan quality.
### Issues
#### 🔴 Critical
- [Issue description with specific location]
#### 🟠 Major
- [Issue description with specific location]
#### 🟡 Minor
- [Issue description with specific location]
#### 🟢 Nitpick
- [Suggestion]
### Quality Assessment
| Check | Status |
|-------|--------|
| Goal is specific and measurable | PASS / FAIL |
| Citations support key decisions | PASS / FAIL |
| Tasks are actionable | PASS / FAIL |
| Edge cases addressed | PASS / FAIL |
### Positive Observations
- [What's done well - always include at least one]What NOT to Do
- Do NOT re-validate format—
plan_savehandles structural validation - Do NOT evaluate code quality (that's code-review's job)
- Do NOT execute or modify the plan during review
- Do NOT skip citation verification for decisions
- Do NOT accept vague goals or ambiguous tasks
- Do NOT forget to note positive observations
Adherence Checklist
Before completing a plan review, verify:
- All 3 quality categories analyzed (Citations, Completeness, Actionability)
- Severity assigned to each finding
- Specific locations noted for all issues
- Quality Assessment table completed
- Positive observations noted
- Output follows the standard format