Planning

Core Principle

Context window = RAM (volatile, limited)
Filesystem     = Disk (persistent, unlimited)
→ Anything important gets written to disk.

Planning tokens are cheaper than implementation tokens. Front-load thinking; scale effort to complexity.

When to Plan

• Full plan (.plan/ directory): multi-file changes, new features, refactors, >5 tool calls
• Flat list (inline checklist): 3-5 file changes, clear scope, no research needed -- write a numbered task list in the conversation or a single progress.md, skip .plan/ scaffolding
• Skip planning: single-file edits, quick lookups, simple questions

Planning Files

Scaffold the .plan/ directory with pre-populated templates using init-plan.sh:

bash init-plan.sh "Feature Name"

This creates .plan/ with task_plan.md, findings.md, and progress.md — each pre-populated with the correct structure. Also adds .plan/ to .gitignore.

Planning files are ephemeral working state — do not commit them. If working on multiple features sequentially, old files are overwritten; the plan captures the current task only.

Plan Template

# Plan: [Feature/Task Name]

## Approach
[1-3 sentences: what and why]

## Scope
- **In**: [what's included]
- **Out**: [what's explicitly excluded]

## Phase 1: [Name]
**Files**: [specific files, max 5-8 per phase]
**Tasks**:
- [ ] [Verb-first atomic task] — `path/to/file.ts`
- [ ] [Next task]
**Verify**: [specific test: "POST /api/users → 201", not "test feature"]
**Exit**: [clear done definition]

## Phase 2: [Name]
...

## Open Questions
- [Max 3, only truly blocking unknowns]

Phase Sizing Rules

Every phase must be context-safe:

• Max 5-8 files touched
• Max 2 dependencies on other phases
• Fits in one 2-4 hour session (implementation + verification + fixes)
• If a phase violates these → split it

Clarifying Questions

Scale to complexity:

• Small task: 0-1 questions, assume reasonable defaults
• Medium feature: 1-2 questions on critical unknowns
• Large project: 3-5 questions (auth, data model, integrations, scope)

Only ask if truly blocking. Make reasonable assumptions for everything else.

Task Rules

• Atomic: one logical unit of work per task
• Verb-first: "Add...", "Create...", "Refactor...", "Verify..."
• Concrete: name specific files, endpoints, components
• Ordered: respect dependencies, sequential when needed
• Verifiable: include at least one validation task per phase

Context Management Rules

Error Protocol

ATTEMPT 1: Diagnose root cause → targeted fix
ATTEMPT 2: Different approach (different tool, library, method)
ATTEMPT 3: Question assumptions → search for solutions → update plan
AFTER 3 FAILURES: Escalate to user with what you tried

Never repeat the exact same failing action. Track attempts, mutate approach.

Iterative Refinement

For complex projects, iterate on the plan before implementing:

1. Draft initial plan
2. Review for gaps, missing edge cases, architectural issues
3. Revise until suggestions become incremental
4. Only then start implementation

5-Question Context Check

If you can answer these, your planning is solid:

Anti-Patterns

Relationship to workflows:plan

This skill provides the methodology for planning (file persistence, phase sizing, context management). The workflows:plan command provides the structured workflow (research agents, issue templates, plan file creation).

Use this skill's principles during any planning activity. Use workflows:plan when creating a full feature plan with research and issue structure.

Integration

• This skill applies as methodology during workflows:plan and workflows:work
• Predecessor: brainstorming — use first when requirements are ambiguous or multiple approaches exist
• Prose quality: writing — use to humanize plan language and remove AI slop from plan documents
• Execution handoff: after the plan is approved, proceed to workflows:work or execute inline
• End of chain: finishing-branch (merge / PR / keep / discard)
• See brainstorming for the full workflow chain diagram