plan-review

What this skill does

# Plan Review

Use this skill to validate implementation plans across completeness, quality, feasibility, and scope dimensions.

## When to Use

After plan is written and user selects "A) review the plan" option.

## Phase 1: Initial Assessment

Run automatic checks across 4 dimensions using simple validation logic (no subagents yet):

### Completeness Check

Scan plan for:
- ✅ All phases have success criteria section
- ✅ Commands for verification present (`make test-`, `pytest`, etc.)
- ✅ Rollback/migration strategy mentioned
- ✅ Edge cases section or error handling
- ✅ Testing strategy defined

**Scoring:**
- PASS: All criteria present
- WARN: 1-2 criteria missing
- FAIL: 3+ criteria missing

### Quality Check

Scan plan for:
- ✅ File paths with line numbers: `file.py:123`
- ✅ Specific function/class names
- ✅ Code examples are complete (not pseudocode)
- ✅ Success criteria are measurable
- ❌ Vague language: "properly", "correctly", "handle", "add validation" without specifics

**Scoring:**
- PASS: File paths present, code complete, criteria measurable, no vague language
- WARN: Some file paths missing or minor vagueness
- FAIL: No file paths, pseudocode only, vague criteria

### Feasibility Check

Basic checks (detailed check needs subagent):
- ✅ References to existing files/functions seem reasonable
- ✅ No obvious impossibilities
- ✅ Technology choices are compatible
- ✅ Libraries mentioned are standard/available

**Scoring:**
- PASS: Seems feasible on surface
- WARN: Some questionable assumptions
- FAIL: Obvious blockers or impossibilities

### Scope Creep Check

Requires research.md memory or brainstorm context:
- ✅ "What We're NOT Doing" section exists
- ✅ Features align with original brainstorm
- ❌ New features added without justification
- ❌ Gold-plating or over-engineering patterns

**Scoring:**
- PASS: Scope aligned with original decisions
- WARN: Minor scope expansion, can justify
- FAIL: Significant scope creep or gold-plating

## Phase 2: Escalation (If Needed)

If **any dimension scores FAIL**, spawn specialized validators:

```typescript
const failedDimensions = {
  completeness: score === 'FAIL',
  quality: score === 'FAIL',
  feasibility: score === 'FAIL',
  scope: score === 'FAIL'
}

// Spawn validators in parallel for failed dimensions
const validations = await Promise.all([
  ...(failedDimensions.completeness ? [Task({
    subagent_type: "completeness-checker",
    description: "Validate plan completeness",
    prompt: `
      Analyze this implementation plan for completeness.

      Plan file: ${planPath}

      Check for:
      - Success criteria (automated + manual)
      - Dependencies between phases
      - Rollback/migration strategy
      - Edge cases and error handling
      - Testing strategy

      Report issues and recommendations.
    `
  })] : []),

  ...(failedDimensions.feasibility ? [Task({
    subagent_type: "feasibility-analyzer",
    description: "Verify plan feasibility",
    prompt: `
      Verify this implementation plan is feasible.

      Plan file: ${planPath}

      Use Serena MCP to check:
      - All referenced files/functions exist
      - Libraries are in dependencies
      - Integration points match reality
      - No technical blockers

      Report what doesn't exist or doesn't match assumptions.
    `
  })] : []),

  ...(failedDimensions.scope ? [Task({
    subagent_type: "scope-creep-detector",
    description: "Check scope alignment",
    prompt: `
      Compare plan against original brainstorm for scope creep.

      Plan file: ${planPath}
      Research/brainstorm: ${researchMemoryPath}

      Check for:
      - Features not in original scope
      - Gold-plating or over-engineering
      - "While we're at it" additions
      - Violations of "What We're NOT Doing"

      Report scope expansions and recommend removals.
    `
  })] : []),

  ...(failedDimensions.quality ? [Task({
    subagent_type: "quality-validator",
    description: "Validate plan quality",
    prompt: `
      Check this implementation plan for quality issues.

      Plan file: ${planPath}

      Check for:
      - Vague language vs. specific actions
      - Missing file:line references
      - Untestable success criteria
      - Incomplete code examples

      Report specific quality issues and improvements.
    `
  })] : [])
])
```

## Phase 3: Interactive Refinement

Present findings conversationally (like brainstorming skill):

```markdown
I've reviewed the plan. Here's what I found:

**Completeness: ${score}**
${if issues:}
- ${issue-1}
- ${issue-2}

**Quality: ${score}**
${if issues:}
- ${issue-1}
- ${issue-2}

**Feasibility: ${score}**
${if issues:}
- ${issue-1}
- ${issue-2}

**Scope: ${score}**
${if issues:}
- ${issue-1}
- ${issue-2}

${if any FAIL:}
Let's address these issues. Starting with ${most-critical-dimension}:

Q1: ${specific-question}
   A) ${option-1}
   B) ${option-2}
   C) ${option-3}
```

### Question Flow

Ask **one question at a time**, wait for answer, then next question.

For each issue:
1. Explain the problem clearly
2. Offer 2-4 concrete options
3. Allow "other" for custom response
4. Apply user's decision immediately
5. Update plan if changes agreed
6. Move to next issue

### Refinement Loop

After addressing all issues:
1. Update plan file with agreed changes
2. Re-run Phase 1 assessment
3. If still FAIL, spawn relevant validators again
4. Continue until all dimensions PASS or user approves WARN

### Approval

When all dimensions PASS or user accepts WARN:

```markdown
Plan review complete! ✅

**Final Scores:**
- Completeness: PASS
- Quality: PASS
- Feasibility: PASS
- Scope: PASS

The plan is ready for execution.
```

If user approved with WARN:

```markdown
Plan review complete with warnings.

**Final Scores:**
- Completeness: PASS
- Quality: WARN (minor file path gaps)
- Feasibility: PASS
- Scope: PASS

Warnings acknowledged. Proceeding with execution.
```

## Plan Updates

When making changes based on review:

1. Read current plan file
2. Apply specific edits using Edit tool
3. Preserve structure and formatting
4. Update only sections with issues
5. Verify changes with re-read

Don't rewrite entire plan - use targeted edits.

## Exit Conditions

**Success:** All PASS or user approves WARN
**Abort:** User requests to skip review and execute anyway
**Restart:** User requests major redesign (back to brainstorm)

## Example Session

```markdown
I've reviewed the plan. Here's what I found:

**Completeness: ⚠️ WARN**
- Phase 2 lacks automated success criteria

**Quality: ✅ PASS**

**Feasibility: ❌ FAIL**
- Plan assumes `src/auth/handler.py` exists - NOT FOUND

**Scope: ❌ FAIL**
- Plan includes "admin dashboard" but brainstorm only mentioned "user dashboard"

Let's address these issues. Starting with scope:

Q1: The plan includes an admin dashboard, but your brainstorm only mentioned a user dashboard. Should we:
   A) Remove admin dashboard (stick to original scope)
   B) Keep it (intentional expansion)
   C) Split admin dashboard into separate plan

User: A

Got it. I'll remove the admin dashboard from the plan.

[Updates plan, removes admin dashboard task]

Next, feasibility:

Q2: The plan references `src/auth/handler.py` but this file doesn't exist. I found `src/security/auth.py:45` with similar functionality. Should we:
   A) Create new `src/auth/handler.py` as planned
   B) Use existing `src/security/auth.py` instead
   C) Rename existing file to match plan

User: B

Makes sense. I'll update the plan to use `src/security/auth.py`.

[Updates plan with correct file paths]

Finally, completeness:

Q3: Phase 2 doesn't have automated success criteria. Should we add:
   A) `make test-auth` command to verify
   B) Specific pytest command
   C) Manual testing steps only

User: A

Perfect. I'll add `make test-auth` verification to Phase 2.

[Updates plan with verification command]

Re-checking plan with fixes...

**Final Scores:**
- Completeness: ✅ PASS
- Quality: ✅ PASS
- Feasibility: ✅ PASS
- Scop