Epic Plan

Planning phase of the Explore-Plan-Implement workflow. Create detailed, phased implementation plans based solely on research findings.

Workflow

1. Locate active workflow: .claude/workflows/*/state.md
2. Verify Explore phase is complete
3. Load research artifacts (codebase-research.md, docs-research.md)
4. Design atomic, verifiable phases
5. Write plan to plan.md
6. Update state.md
7. Present summary for human review

Prerequisites

• Explore phase must be complete
• Research artifacts must exist in workflow directory

If prerequisites not met:

⚠️ Cannot create plan - Explore phase incomplete
Run `/epic:explore [feature]` first.

Phase Design Principles

Each phase must be:

• Atomic - Independently verifiable
• Sequential - Foundation for later phases
• Right-sized - Completable in one focused session

Phase Structure

## Phase N: [Descriptive Name]

### Changes
| File | Action | Description |
|------|--------|-------------|
| `path/to/file.ts:45-67` | Modify | [what changes] |
| `path/to/new.ts` | Create | [what it does] |

### Implementation Details
[Specific code changes, following patterns from research]

### Verification
**Automated:**
- [ ] `npm test` - [what it verifies]
- [ ] `npm run lint` - passes
- [ ] `npm run typecheck` - passes

**Manual:**
- [ ] [Specific check requiring human verification]

Plan Quality Checklist

Check	Requirement
Research-based	All decisions reference research findings
Specific	File paths include line numbers
Verifiable	Every phase has automated + manual checks
Complete	Rollback plan and success criteria defined
Right-sized	No phase too large for one session

Required Plan Sections

1. Goal - Clear statement of outcome
2. Approach Summary - Why this approach (from research)
3. Phases - Detailed phase definitions
4. Rollback Plan - How to undo if needed
5. Success Criteria - Measurable completion criteria
6. Open Questions - Decisions needing human input

See references/plan-template.md for full structure.

Plan Validation

After writing the plan, invoke the plan-validator agent to validate it before presenting to user.

Agent Invocation

Task tool:
  subagent_type: epic:plan-validator
  run_in_background: false
  prompt: |
    Validate the implementation plan at: .claude/workflows/[slug]/plan.md
    Research artifacts: .claude/workflows/[slug]/codebase-research.md
    Write validation report to: .claude/workflows/[slug]/plan-validation.md

IMPORTANT: Always launch a fresh agent. Never use the resume parameter.

Handling Validation Results

Verdict	Action
PASS	Present plan to user for approval
PASS WITH CONCERNS	Present concerns, ask user to review
NEEDS REVISION	Fix issues, re-validate (max 3 attempts)

NEEDS REVISION Protocol

When validation returns "NEEDS REVISION":

1. Read validation report to identify specific issues
2. Categorize issues:
   • Fixable by agent: Missing details, unclear steps, incomplete verification
   • Requires human input: Architectural decisions, ambiguous requirements
3. If fixable by agent (attempt < 3):
   • Apply targeted fixes to plan.md
   • Re-run plan-validator
   • Increment attempt counter
4. If requires human input OR attempt >= 3:
   • Present issues to user via AskUserQuestion
   • Options: "Help me fix these", "I'll revise manually", "Proceed anyway"
   • Wait for user guidance

⚠️ Plan Validation Failed (Attempt 2/3)

Issues found:
1. Phase 2 verification steps incomplete
2. Rollback plan missing for database changes

Auto-fixing: Adding verification steps...
Re-validating...

Validation Failure Escalation

Attempt	Action
1	Auto-fix if possible, re-validate
2	Auto-fix if possible, re-validate
3	STOP - require human intervention

After 3 failed attempts:

⚠️ Plan validation failed 3 times.

Remaining issues:
- [issue list]

Options:
1. I'll help fix specific issues (tell me which)
2. Revise the plan manually, then /epic:plan --revalidate
3. Skip validation and proceed (not recommended)

Output Format

✓ Plan Phase Complete

Feature: [description]
Phases: [N] phases defined
Artifact: .claude/workflows/[slug]/plan.md

Validation: [PASS/PASS WITH CONCERNS]
- Completeness: ✓
- Feasibility: ✓

Phase Summary:
1. [Phase 1] - [files affected]
2. [Phase 2] - [files affected]

Next: Review plan, then run /epic:implement

Leverage Hierarchy

Error in Research → 1000s of bad lines
Error in Plan     → 100s of bad lines  ← THIS PHASE
Error in Code     → ~1 bad line

This is the second-highest leverage point. Human review here prevents cascading errors.

Quality Rules

1. Research is truth - Base ALL decisions on research, never training data
2. Specificity required - Vague plans create vague implementations
3. Verification mandatory - Every phase must have testable checks
4. Human decisions flagged - Don't assume; ask when choices exist
5. Plan is contract - Implementation follows this exactly

References

• references/plan-template.md - Full implementation plan template