Planning - Feature Execution Planning

A specialized planning skill for breaking down complex features into executable tracks and beads with clear dependencies, file scopes, and verification criteria.

code

┌─────────────────────────────────────────────────────────────────┐
│                     PLANNING PIPELINE                           │
├─────────────────────────────────────────────────────────────────┤
│  Discovery → Approach → Spike (optional) → Execution Plan       │
│      ↓           ↓            ↓                  ↓              │
│  [CHECKPOINT] [CHECKPOINT] [CHECKPOINT]    [HANDOFF]            │
└─────────────────────────────────────────────────────────────────┘

AI Behavior Guidelines

When to ASK User (Stop and Confirm)

•Before moving to next phase → Always checkpoint
•When discovery reveals > 3 open questions
•When multiple approaches have similar trade-offs (no clear winner)
•When estimated effort > 1 day
•When feature touches > 5 major areas of codebase
•When external dependencies or APIs are involved

When to Proceed Autonomously

•Codebase exploration and pattern identification
•Template filling with known information
•Generating options for user to choose
•Creating dependency graphs
•Estimating bead sizes based on file count/complexity

Communication Style

•Be concise in checkpoints
•Use tables for comparisons
•Always show next steps
•Highlight blockers and risks prominently

Pipeline Phases

Phase 1: Discovery

Goal: Understand the feature scope and codebase context.

Input	Output
Feature request	`history/<feature>/discovery.md`

Steps:

•Analyze the feature requirements thoroughly
•Explore relevant codebase areas using finder/Grep
•Identify existing patterns and conventions
•Map affected components and their relationships
•Document findings in discovery.md
•→ CHECKPOINT: Ask user to confirm understanding

Discovery Template:

markdown

# Discovery: <Feature Name>

## Feature Summary
<Brief description of what we're building>

## Codebase Context
- **Affected Areas**: <list of files/directories>
- **Existing Patterns**: <relevant patterns found>
- **Dependencies**: <external/internal dependencies>

## Technical Constraints
- <constraint 1>
- <constraint 2>

## Open Questions
- [ ] <question needing clarification>

## Risk Assessment
| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| <risk> | High/Med/Low | High/Med/Low | <strategy> |

## Research Notes
<findings from codebase exploration>

Checkpoint Output:

code

═══════════════════════════════════════════════════════════
[CHECKPOINT: DISCOVERY_COMPLETE]
═══════════════════════════════════════════════════════════

📋 Feature: <name>
📁 Affected Areas: <count> files across <count> directories
⚠️  Open Questions: <count>
🔴 Risks Identified: <count>

Key Findings:
• <finding 1>
• <finding 2>

❓ Questions for You:
1. <question>
2. <question>

👉 Ready to proceed to Approach phase? (yes/no/clarify)
═══════════════════════════════════════════════════════════

Phase 2: Approach Design

Goal: Define high-level implementation strategy.

Input	Output
discovery.md	`history/<feature>/approach.md`

Steps:

•Identify 2-3 potential implementation approaches
•Evaluate trade-offs for each approach
•Recommend approach with clear justification
•Define success criteria and verification strategy
•→ CHECKPOINT: Get user approval on approach

Approach Template:

markdown

# Approach: <Feature Name>

## Options Considered

### Option A: <Name>
- **Description**: <how it works>
- **Pros**: <advantages>
- **Cons**: <disadvantages>
- **Risk Level**: Low/Medium/High
- **Effort**: S/M/L/XL

### Option B: <Name>
...

## Comparison Matrix
| Criteria | Option A | Option B | Option C |
|----------|----------|----------|----------|
| Complexity | ⭐⭐ | ⭐⭐⭐ | ⭐ |
| Performance | ⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ |
| Maintainability | ⭐⭐⭐ | ⭐⭐ | ⭐⭐ |
| Time to implement | ⭐⭐ | ⭐ | ⭐⭐⭐ |

## Recommended Approach
**Selected**: Option <X>

**Justification**:
<Detailed reasoning>

## Success Criteria
- [ ] <measurable criterion 1>
- [ ] <measurable criterion 2>

## Verification Strategy
- **Unit Tests**: <what to test>
- **Integration Tests**: <what to test>
- **Manual Verification**: <steps>

Checkpoint Output:

code

═══════════════════════════════════════════════════════════
[CHECKPOINT: APPROACH_SELECTED]
═══════════════════════════════════════════════════════════

🎯 Recommended: <Option Name>

| Option | Effort | Risk | Score |
|--------|--------|------|-------|
| A: <name> | M | Low | ⭐⭐⭐ ← Recommended |
| B: <name> | L | Med | ⭐⭐ |

Why this approach:
• <reason 1>
• <reason 2>

⚠️  Trade-offs to accept:
• <trade-off>

👉 Approve this approach? (yes/no/option-b/discuss)
═══════════════════════════════════════════════════════════

Phase 3: Spike (Optional)

Goal: Validate risky assumptions through time-boxed experiments.

Input	Output
approach.md, risk items	`.spikes/<feature>/<spike-id>/`, `history/<feature>/spike-learnings.md`

When to Spike (AI should suggest spike if):

•New technology/library integration
•Unclear performance characteristics
•Complex algorithm implementation
•Third-party API integration
•Risk level marked as "High" in discovery

Spike Rules:

Rule	Description
Time-boxed	Max 2-4 hours, set timer
Throwaway code	Code in `.spikes/` is disposable
Document learnings	Focus on what we learned, not just results
Update approach	Revise approach.md based on findings
Go/No-Go decision	Spike must end with clear recommendation

Spike Template:

markdown

# Spike: <Spike Name>

## Hypothesis
<What we're trying to validate>

## Time Box
- **Allocated**: <X> hours
- **Started**: <timestamp>
- **Ended**: <timestamp>

## Experiment
<What we tried>

## Results
- ✅ <what worked>
- ❌ <what didn't work>

## Learnings
1. <learning>
2. <learning>

## Recommendation
- [ ] Proceed with original approach
- [ ] Modify approach: <how>
- [ ] Abandon approach, use alternative

Checkpoint Output:

code

═══════════════════════════════════════════════════════════
[CHECKPOINT: SPIKE_COMPLETE]
═══════════════════════════════════════════════════════════

🧪 Spike: <name>
⏱️  Time spent: <X>h / <Y>h allocated

Results:
✅ <validated assumption>
❌ <invalidated assumption>

📝 Key Learning: <most important insight>

Recommendation: <proceed/modify/abandon>

👉 Accept spike findings? (yes/rerun/discuss)
═══════════════════════════════════════════════════════════

Phase 4: Execution Plan

Goal: Create detailed, executable work breakdown.

Input	Output
approach.md, spike-learnings.md	`history/<feature>/execution-plan.md`

Core Concepts:

Concept	Definition	Constraint
Track	Parallel work stream	Non-overlapping file scopes
Bead	Atomic work unit	15-60 min, max 3 dependencies
File Scope	Glob patterns per track	Must not overlap between tracks

Bead Sizing Guide:

Size	Time	Files	Complexity	Example
S	15-30 min	1 file	Simple logic	Add prop, fix typo
M	30-60 min	2-3 files	Moderate logic	New component with hook
L	60-90 min	3-5 files	Complex logic	Feature with API call
XL	>90 min	>5 files	Very complex	⚠️ Must split!

Execution Plan Template:

markdown

# Execution Plan: <Feature Name>

## Overview
- **Epic ID**: <unique-id>
- **Total Estimated Effort**: <X>h
- **Parallel Tracks**: <count>
- **Critical Path**: <bead-ids>

## Tracks

### Track 1: <Track Name>
**Scope**: `src/components/**/*.tsx`, `src/hooks/use<Feature>*.ts`
**Dependencies**: None
**Estimated**: <X>h

#### Bead 1.1: <Bead Title>
- **Size**: S/M/L
- **Description**: <what to do>
- **Files**: 
  - `src/components/Feature.tsx` (create)
  - `src/hooks/useFeature.ts` (modify)
- **Acceptance**: <how to verify completion>
- **Dependencies**: None

#### Bead 1.2: <Bead Title>
- **Size**: M
- **Dependencies**: Bead 1.1
...

### Track 2: <Track Name>
**Scope**: `src/api/**/*.ts`, `src/services/<feature>*.ts`
**Dependencies**: None
...

## Dependency Graph
\`\`\`
Track 1: [1.1] ──▶ [1.2] ──▶ [1.3]
                      │
Track 2: [2.1] ──▶ [2.2] ──┴──▶ [Integration]
                               │
Track 3: [3.1] ──▶ [3.2] ──────┘
\`\`\`

## Critical Path
1. Bead 1.1 (blocker for all)
2. Bead 2.2 (API layer)
3. Integration bead

## Verification Checklist
- [ ] All beads completed
- [ ] Tests passing: `yarn test`
- [ ] No type errors: `yarn build`
- [ ] Lint clean: `yarn lint`
- [ ] Manual verification done

Structured Output for Orchestrator

IMPORTANT: Every execution plan MUST include this YAML block for machine parsing by the orchestrator skill:

yaml

# execution-plan.yaml
epic:
  id: "<EPIC-ID>"
  name: "<Feature Name>"
  total_effort_hours: <number>
  
tracks:
  - id: "track-1"
    name: "<Track Name>"
    scope:
      - "src/components/**/*.tsx"
      - "src/hooks/use*.ts"
    dependencies: []
    beads:
      - id: "bead-1.1"
        title: "<Bead Title>"
        size: "M"  # S/M/L
        effort_minutes: 45
        files:
          - path: "src/components/Feature.tsx"
            action: "create"  # create/modify/delete
          - path: "src/hooks/useFeature.ts"
            action: "modify"
        dependencies: []
        acceptance: "<verification criteria>"
        
      - id: "bead-1.2"
        title: "<Bead Title>"
        size: "S"
        effort_minutes: 20
        files:
          - path: "src/components/Feature.tsx"
            action: "modify"
        dependencies: ["bead-1.1"]
        acceptance: "<verification criteria>"

  - id: "track-2"
    name: "<Track Name>"
    scope:
      - "src/services/**/*.ts"
    dependencies: []
    beads:
      - id: "bead-2.1"
        ...

orchestration:
  parallel_tracks: 2
  critical_path: ["bead-1.1", "bead-2.1", "bead-integration"]
  estimated_total_hours: 4
  suggested_workers: 2

Handoff Protocol

To Orchestrator

When plan is complete and approved, output:

code

═══════════════════════════════════════════════════════════
[HANDOFF: READY_FOR_ORCHESTRATION]
═══════════════════════════════════════════════════════════

📋 Epic: <EPIC-ID> - <Feature Name>
📊 Tracks: <count> parallel tracks
🔢 Beads: <total count> work units
⏱️  Estimated: <X>h total

Track Summary:
| Track | Beads | Effort | Can Start |
|-------|-------|--------|-----------|
| 1: UI | 4 | 2h | ✅ Now |
| 2: API | 3 | 1.5h | ✅ Now |
| 3: Integration | 2 | 1h | ⏳ After 1,2 |

Files Generated:
• history/<feature>/discovery.md
• history/<feature>/approach.md
• history/<feature>/execution-plan.md
• history/<feature>/execution-plan.yaml

👉 Start orchestration with: "orchestrate <EPIC-ID>"
═══════════════════════════════════════════════════════════

To Worker

Each bead assignment includes:

yaml

worker_assignment:
  bead_id: "bead-1.1"
  track_id: "track-1"
  epic_id: "<EPIC-ID>"
  
  task:
    title: "<Bead Title>"
    description: "<detailed description>"
    
  scope:
    files:
      - path: "src/components/Feature.tsx"
        action: "create"
    allowed_patterns:
      - "src/components/**/*.tsx"
    forbidden_patterns:
      - "src/services/**"  # belongs to track-2
      
  context:
    dependencies_completed: ["bead-0.1"]
    related_files:
      - "src/types/feature.ts"
      
  acceptance:
    criteria: "<what defines done>"
    verify_command: "yarn test src/components/Feature.test.tsx"

Quick Reference

Phase	Output	Checkpoint	Key Question
Discovery	discovery.md	DISCOVERY_COMPLETE	What exists and what do we need?
Approach	approach.md	APPROACH_SELECTED	How should we build it?
Spike	spike-learnings.md	SPIKE_COMPLETE	Does our approach work?
Execution	execution-plan.md + .yaml	READY_FOR_ORCHESTRATION	What exactly, in what order?

Tools to Use

Tool	When to Use
finder	Explore codebase structure, find patterns
Grep	Find specific implementations, usages
Read	Examine file contents in detail
oracle	Get architectural guidance for complex decisions
mermaid	Visualize dependency graphs

Anti-Patterns to Avoid

❌ Don't	✅ Do Instead
Skip checkpoints	Always pause for user confirmation
Create XL beads	Split into S/M/L beads
Overlap file scopes	Ensure tracks have exclusive scopes
Assume requirements	Ask clarifying questions
Plan without exploring	Always run discovery first
Create circular dependencies	Use DAG (directed acyclic graph)