Planning

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:

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

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

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

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

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

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

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

# execution-plan.yaml