Plan Review Skill | Agent Skills

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

Agent Skills: Plan Review

Install this agent skill to your local

Skill Files