---

name: planning description: Generate comprehensive execution plans for features, epics, or large tasks. Use when asked to plan a feature, create a roadmap, break down work into tracks/beads, or design implementation strategy.

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.

Copy┌─────────────────────────────────────────────────────────────────┐
│                     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.

Steps:

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

Discovery Template:

Copy# 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:

Copy═══════════════════════════════════════════════════════════
[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.

Steps:

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

Approach Template:

Copy# 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:

Copy═══════════════════════════════════════════════════════════
[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.

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:

Spike Template:

Copy# 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:

Copy═══════════════════════════════════════════════════════════
[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.

Core Concepts:

Bead Sizing Guide:

Execution Plan Template:

Copy# 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:

Copy# 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:

Copy═══════════════════════════════════════════════════════════
[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:

Copyworker_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

Tools to Use

Anti-Patterns to Avoid