/epcc-plan

name: epcc-plan
description: Plan phase of EPCC workflow - strategic design before implementation
version: 3.1.0
argument-hint: "[feature-or-task-to-plan]"

EPCC Plan Command

You are in the **PLAN** phase of the Explore-Plan-Code-Commit workflow. Transform exploration insights into actionable strategy through **collaborative planning**.

**Opening Principle**: High-quality plans transform ambiguity into executable tasks by surfacing hidden assumptions and documenting decisions with their rationale.

@../docs/EPCC_BEST_PRACTICES.md - Comprehensive guide covering clarification strategies, error handling planning, sub-agent delegation patterns, and interactive phase best practices

⚠️ **IMPORTANT**: This phase is for PLANNING ONLY. Do NOT write implementation code. Focus on:

• Creating detailed plans
• Breaking down tasks
• Assessing risks
• Documenting in EPCC_PLAN.md

Implementation happens in CODE phase.

Planning Target

$ARGUMENTS

🎯 Planning Philosophy

**Core Principle**: Draft → Present → Iterate → Finalize only after approval. Plans are collaborative, not dictated.

Planning Workflow

1. **Clarify** → Understand requirements (ask questions if unclear) 2. **Draft** → Create initial plan with documented assumptions 3. **Present** → Share plan for review 4. **Iterate** → Refine based on feedback 5. **Finalize** → Lock down plan only after user approval

**Never finalize without user review.**

Clarification Strategy

When to Ask Questions

**✅ Ask when:**

• Requirements vague or ambiguous ("improve performance" → how much? where?)
• Multiple valid approaches exist (which to choose?)
• Ambiguous scope boundaries (what's in/out?)
• Trade-offs need decisions (complexity vs performance? speed vs quality?)
• User preferences unknown (which option?)

**❌ Don't ask when:**

• EPCC_EXPLORE.md already documents it (read first)
• PRD.md already clarified it (check product requirements if available)
• TECH_REQ.md already defined it (check technical decisions if available)
• It's an implementation detail (defer to CODE phase)
• You can document multiple options (present alternatives in plan)

Question Patterns

**Check context files first**: Read EPCC_EXPLORE.md (brownfield) + PRD.md (product) + TECH_REQ.md (technical) → use found context → ask about gaps only

**Draft-driven**: Create draft with documented assumptions → present → iterate → finalize only after approval

**Technical decisions**: 2-4 clear options → use AskUserQuestion if needed → avoid asking about code-level details

Context Gathering

Check for available context sources:

# Brownfield: Use exploration findings
if [ -f "EPCC_EXPLORE.md" ]; then
    # Read: Tech stack, patterns, testing approach, constraints
    # Follow: Existing architecture patterns, reuse identified components
fi

# Greenfield: Use best practices
else
    # Read: Tech stack from PRD.md, TECH_REQ.md, or user input
    # Apply: Industry best practices, standard patterns
fi

# Check product requirements
if [ -f "PRD.md" ]; then
    # Use: Requirements, user stories, acceptance criteria, features
elif [ -f "EPCC_PRD.md" ]; then
    # Legacy file name support
else
    # Gather product requirements from user input
fi

# Check technical requirements
if [ -f "TECH_REQ.md" ]; then
    # Use: Architecture decisions, tech stack rationale, data models, integrations, security approach, performance strategy
fi

**Extract key information:**

• **Brownfield**: Existing patterns from EPCC_EXPLORE.md, tech stack, constraints, similar implementations
• **Greenfield**: Tech stack from TECH_REQ.md (if available), product requirements from PRD.md (if available), industry best practices
• **Either**: Requirements, acceptance criteria, constraints, technical decisions

Planning Framework

Step 1: Define Objectives

**What are we building and why?**

• Clear goal statement
• Problem being solved
• Success criteria (how will we know it's done?)
• User value delivered

Step 2: Break Down Tasks

**Principles:**

• Break into <4 hour chunks (testable units of work)
• Identify dependencies (what must happen first?)
• Assess risk (what could go wrong?)
• Estimate realistically (when in doubt, double estimate)

**Pattern** (adapt to your plan):

## Task Breakdown

### Phase 1: Foundation (~X hours)
1. **Task Name** (Xh)
   - What it does
   - Dependencies: [None / Task Y must complete first]
   - Risk: [Low/Medium/High - what could go wrong]
   - Estimated effort

2. **Task Name** (Xh)
   - Description
   - Dependencies
   - Risk
   - Estimate

### Phase 2: Core Implementation (~X hours)
...

**Anti-Patterns:**

• ❌ Tasks too large (>1 day = break down further)
• ❌ Missing dependencies (creates blocking issues)
• ❌ Ignoring risk (complex areas need buffers)
• ❌ Unrealistic estimates (hope is not a strategy)

Step 3: Design Technical Approach

**High-level architecture**:

• Component structure (how pieces fit together)
• Data flow (how information moves)
• Integration points (external systems, APIs)
• Technology choices (justified with rationale)

**If EPCC_EXPLORE.md exists**: Follow existing patterns (brownfield) **If TECH_REQ.md exists**: Use architecture decisions and tech stack from TRD **If greenfield without TRD**: Design from PRD + industry best practices

Step 4: Identify Risks

**What could go wrong?**

| Risk | Impact | Likelihood | Mitigation | |------|--------|------------|------------| | [Risk description] | H/M/L | H/M/L | [How to address/prevent] |

**Common risk categories:**

• Technical (new technology, complexity, integration)
• Timeline (estimates off, dependencies blocking)
• Requirements (changing scope, unclear needs)
• Resources (team capacity, budget constraints)

Step 5: Define Test Strategy

**How will we verify it works?**

• Unit tests (what components to test)
• Integration tests (what interactions to verify)
• Edge cases (boundary conditions, error scenarios)
• Acceptance criteria (