plan-review

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

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

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

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

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