Master Planning

Overview

A skill for solving the execution problem — staying focused, organized, and on-track during complex, multi-step development tasks. Uses structured planning documents to track goals, decompose work into phases, record decisions, and maintain progress — ensuring Claude never loses context during long coding sessions.

When to Use

• Multi-step tasks requiring 3+ actions
• Feature implementations spanning multiple files
• Research-heavy tasks where findings inform later steps
• Refactoring projects with many dependencies
• Any task where you might lose track of the goal mid-way
• Tasks requiring sequential decisions that build on each other

Quick Start

Copy
# Create a plan for a feature
claude "Plan the implementation of user authentication with JWT"

# Create a phased migration plan
claude "Plan migrating from REST to GraphQL for the user service"

# Plan a complex refactor
claude "Plan breaking the monolithic UserService into separate services"

The Planning Framework

3-Document Pattern

Every complex task gets three tracking documents:

Document	Purpose	Update Frequency
task_plan.md	Goals, phases, decisions, errors	After each phase
findings.md	Research, discoveries, resources	During research
progress.md	Session log, outcomes, test results	Throughout

task_plan.md Template

Copy
# Task: [Clear, specific goal]

## Objective
[One paragraph: what we're building and why]

## Success Criteria
- [ ] [Measurable outcome 1]
- [ ] [Measurable outcome 2]
- [ ] [Measurable outcome 3]

## Phases
- [ ] Phase 1: Research & Analysis
- [ ] Phase 2: Design & Architecture
- [ ] Phase 3: Implementation
- [ ] Phase 4: Testing & Validation
- [ ] Phase 5: Documentation & Cleanup

## Phase Details

### Phase 1: Research & Analysis
- [ ] Review existing codebase patterns
- [ ] Identify dependencies and impact areas
- [ ] Research best practices
- [ ] Document findings in findings.md

### Phase 2: Design & Architecture
- [ ] Define data models / interfaces
- [ ] Design API contracts
- [ ] Plan file structure
- [ ] Get approval before proceeding

### Phase 3: Implementation
- [ ] Implement core logic
- [ ] Add error handling
- [ ] Wire up routes / UI
- [ ] Integrate with existing systems

### Phase 4: Testing & Validation
- [ ] Write unit tests
- [ ] Write integration tests
- [ ] Manual testing
- [ ] Edge case verification

### Phase 5: Documentation & Cleanup
- [ ] Update API docs
- [ ] Add inline documentation
- [ ] Remove dead code
- [ ] Update README if needed

## Decisions Log

| Decision | Options Considered | Choice | Rationale | Date |
|----------|-------------------|--------|-----------|------|
| | | | | |

## Errors & Blockers

| Error | Phase | Attempted Fix | Resolution |
|-------|-------|---------------|------------|
| | | | |

## Risks

| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| | | | |

findings.md Template

Copy
# Research Findings

## Existing Patterns
[What patterns already exist in the codebase]

## Dependencies Identified
[What this task depends on / what depends on this]

## External Resources
[Links, docs, examples that informed decisions]

## Key Discoveries
[Unexpected findings that changed the plan]

progress.md Template

Copy
# Progress Log

## Session: [Date]

### Completed
- [x] Phase 1: Research
  - Found existing auth middleware at src/middleware/auth.ts
  - Current approach uses session cookies

### In Progress
- [ ] Phase 2: Design
  - Drafted JWT token structure
  - Pending: refresh token strategy

### Blockers
- Need to decide on token storage (httpOnly cookie vs localStorage)

### Next Steps
1. Finalize token storage approach
2. Begin Phase 3 implementation

The 6 Planning Rules

1. Create Plan First

Never start complex work without a plan. Even a rough plan prevents wasted effort.

2. Read Before Decide

Re-read the plan before every major decision. Ensures consistency with earlier choices.

3. Update After Act

After completing any phase or making a decision, update the plan immediately.

4. Two-Action Rule

After every 2 significant actions (file edits, searches, tool calls), pause and check:

• Am I still aligned with the plan?
• Should I update findings or progress?

5. Phase Gates

Don't start a new phase until the current phase is marked complete. This prevents half-finished work.

6. Fail Fast, Document

When something doesn't work, document it immediately in the Errors table. Don't repeat failed approaches.

Planning Depth by Task Size

Task Complexity	Documents	Phase Detail
Small (1-3 files)	None needed	Mental plan is fine
Medium (3-10 files)	task_plan.md only	3-4 phases
Large (10+ files)	All 3 documents	5+ phases with subtasks
Multi-session	All 3 + CLAUDE.md memory	Full detail, session handoffs

Estimation

Story Points

Points	Scope	Time Estimate
1	Single function change	Minutes
2	Single file with tests	< 1 hour
3	Multiple files, one module	1-2 hours
5	Cross-module changes	2-4 hours
8	Multi-system integration	4-8 hours
13	Major feature / refactor	Multi-session

Risk Multipliers

• Unfamiliar codebase: 2x
• No test coverage: 1.5x
• External API dependencies: 1.5x
• Database schema changes: 2x
• Breaking API changes: 2x

Best Practices

1. Start with the end in mind — Define success criteria before writing any code
2. Decompose aggressively — If a phase has more than 5 subtasks, split it
3. Time-box research — Set a limit for Phase 1; avoid analysis paralysis
4. Document decisions in real-time — Don't rely on memory
5. Include rollback plans — How to undo each phase if something goes wrong
6. Review the plan at session start — Re-read before resuming work
7. Keep plans living — Update as understanding evolves; plans are not contracts
8. Celebrate milestones — Mark phases complete; it maintains momentum
9. Plan for testing early — Don't leave tests for the end
10. Share the plan — If working with others, the plan is the communication tool