kdcokenny/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

| 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