plan

Core Principle

Some tasks fail when rushed. Recognize when one-shot execution will underdeliver, and choose a slower process that guarantees success.

This skill auto-evolves: learn which tasks need plans, which don't, and which planning strategies work for each type of goal.

Check strategies.md for planning approaches. Check outcomes.md for tracking and learning.

The Planning Decision

Before executing, ask:

Signal	One-shot OK	Plan needed
Task done before successfully	✅
Clear single deliverable	✅
Reversible if wrong	✅
Multiple components		✅
Dependencies between steps		✅
High stakes / hard to redo		✅
Ambiguous success criteria		✅
Estimated >30 min work		✅

Default: When uncertain, plan. A quick plan costs minutes; a failed one-shot costs hours.

Plan Depth Levels

Level	When	Format
L0	Trivial, done before	No plan, just execute
L1	Simple, low risk	Mental checklist, no doc
L2	Medium complexity	Bullet list, share with human
L3	Complex, multi-step	Detailed plan with milestones
L4	High stakes, novel	Full plan + human validation required

Plan Format (L2-L4)

📋 Plan: [Goal]

Context: [Why this needs planning]

Steps:
1. [Step] — [output/checkpoint]
2. [Step] — [output/checkpoint]
3. [Step] — [output/checkpoint]

Risks:
- [Risk] → [mitigation]

Estimated time: [X hours/days]
Validation needed: [Yes/No]

Ready to start?

Validation Learning

Track which plan types need human validation:

### Auto-Execute (no validation needed)
- refactor/small: L2 plans [10+ successful]
- deploy/staging: L2 plans [15+ successful]

### Validate First
- feature/new: L3+ plans [human wants to review scope]
- migration/data: L4 plans [high risk]

### Learning
- api/integration: testing L2 auto-execute [3/5 runs]

Promotion rule: After 5+ successful auto-executes of a plan type, confirm: "Should I auto-start [type] plans without validation?"

Outcome Tracking

After each planned task completes, record:

## [Date] [Task Type]
- Plan level: L3
- Strategy: [approach used]
- Outcome: ✅ success | ⚠️ partial | ❌ failed
- Lesson: [what worked/didn't]
- Adjustment: [change for next time]

Strategy Learning

Different goals need different planning strategies. Track what works:

### Code Features
- ✅ Works: API design first, then implementation
- ❌ Failed: Parallel implementation without interface agreement
- Adjustment: Always define interfaces before coding

### Migrations  
- ✅ Works: Dry-run → staged rollout → full
- ❌ Failed: Big bang migration without rollback plan
- Adjustment: Always require rollback step in migration plans

### Research
- ✅ Works: Timeboxed exploration with checkpoints
- ❌ Failed: Open-ended research without scope limits
- Adjustment: Always set max time and output format upfront

Plans should get better over time. Track patterns:

Length optimization: - Task type X: L4 plans were overkill → demote to L3 - Task type Y: L2 plans missed edge cases → promote to L3

Component optimization: - Always include [X] for [task type] — helped 5+ times - Skip [Y] for [task type] — never used, wasted time

Anti-Patterns

Don't	Do instead
Plan everything	Learn what doesn't need planning
Same plan depth for all tasks	Adapt depth to task type
Ignore failed plans	Track outcomes, adjust strategy
Over-plan familiar tasks	Demote plan level after successes
Under-plan novel tasks	Default to higher plan level
Static planning approach	Evolve strategy per task type

Empty tracking sections = early stage. Execute, track outcomes, learn. The goal is adaptive planning that matches effort to need.

Installation