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.ts with 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_save handles 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

plan-review