Structured Planning

Overview

Structured planning converts vague requirements into approved, documented implementation plans before any code is written. It forces clarifying questions, approach comparison with trade-offs, and explicit user approval — preventing the most common cause of wasted effort: building the wrong thing. Every task, regardless of perceived simplicity, goes through this process.

Announce at start: "I'm using the planning skill to create a structured implementation plan."

Trigger Conditions

User requests a new feature, enhancement, or change
A bug fix requires more than a one-line change
Refactoring work spanning multiple files
Any task where the approach is not already documented and approved
Transition from brainstorming skill with an approved design
```
/plan
```
command invoked

Phase 1: Context Gathering

Goal: Understand the codebase and existing patterns before asking questions.

Read relevant files, docs, recent commits, and CLAUDE.md
Check memory files for known project context, stack, and conventions
Review existing plans in
```
docs/plans/
```
for related work
Identify existing patterns the new work should follow
Note technical constraints discovered during exploration

STOP — Do NOT proceed to Phase 2 until:

You have explored the relevant parts of the codebase
You understand the existing architecture and patterns
You have checked memory files for prior decisions

Phase 2: Clarifying Questions

Goal: Eliminate ambiguity by asking targeted questions one at a time.

Ask ONE question per message — never overwhelm with multiple questions
Prefer multiple choice questions when possible
Study the codebase before asking — do not ask what you can discover
Convert vague requirements into specific, testable criteria

Question Category Priority

Priority	Category	Example Question
1	Purpose	"What problem does this solve? Who is it for?"
2	Success criteria	"How will we know it works? What does 'done' look like?"
3	Constraints	"Are there performance, compatibility, or timeline constraints?"
4	Non-goals	"What should we explicitly NOT build?"
5	Existing patterns	"Should we follow the pattern used in X, or is a new approach needed?"
6	Edge cases	"What should happen when [boundary condition]?"

Question Rules

Rule	Rationale
One question per message	Prevents cognitive overload
Multiple choice preferred	Faster to answer, reduces ambiguity
Research before asking	Respect user's time — discover what you can
Testable criteria	Vague answers lead to vague implementations

STOP — Do NOT proceed to Phase 3 until:

You understand the purpose and success criteria
You have identified constraints and non-goals
No critical ambiguities remain

Phase 3: Approach Design

Goal: Propose 2-3 concrete approaches with trade-offs and a clear recommendation.

For each approach, include:

Section	Content
Architecture summary	2-3 sentences describing the approach
Key files	Exact paths to create/modify
Dependencies	External deps or breaking changes
Trade-offs	Explicit pros and cons
Effort estimate	Number of tasks (not hours)
Risk level	Low / Medium / High with explanation

Approach Selection Decision Table

Factor	Weight	How to Evaluate
Alignment with existing patterns	High	Does it match current codebase conventions?
Simplicity	High	Fewest moving parts that meet requirements
Testability	Medium	Can each component be independently tested?
Future extensibility	Low	Only consider if user mentioned future plans
Performance	Varies	Only if user specified performance constraints

Lead with your recommended approach. Explain why it is the best choice given the constraints. Present alternatives to show you considered the trade-off space.

STOP — Do NOT proceed to Phase 4 until:

You have proposed at least 2 approaches
Each approach has trade-offs documented
You have made a clear recommendation with reasoning

Phase 4: Plan Documentation

Goal: Write a detailed, executable plan document and get explicit approval.

Plan Document Format

markdown

# [Feature Name] Implementation Plan

**Goal:** [One sentence]
**Architecture:** [2-3 sentences]
**Approach:** [Which approach was chosen and why]

---

### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/file.ext`
- Modify: `exact/path/to/existing.ext`
- Test: `tests/exact/path/to/test.ext`

**Steps:**
1. Write the failing test
2. Run test to verify it fails
3. Write minimal implementation
4. Run test to verify it passes
5. Commit

**Verification:** [Exact command to verify this task]

Plan Quality Checklist

Criterion	Check
Every task has exact file paths	No "somewhere in src/"
Every task has a verification command	No "eyeball it"
Tasks are ordered by dependency	No forward references
Tasks are 2-5 minutes each	No "implement the whole module"
TDD steps are explicit	RED-GREEN-REFACTOR per task

Save the plan to

docs/plans/YYYY-MM-DD-<feature>.md

STOP — Do NOT proceed to Phase 5 until:

Plan document is written and saved
Every task has file paths, steps, and verification
User has explicitly approved the plan (said "yes", "approved", "go ahead", etc.)

Phase 5: Transition to Execution

Goal: Hand off the approved plan to the appropriate execution skill.

Transition Decision Table

Situation	Next Skill	Rationale
Standard implementation (< 10 tasks)	`task-management`	Sequential tracked execution
Large implementation (10+ independent tasks)	`subagent-driven-development`	Parallel execution with review gates
Autonomous development session	`autonomous-loop`	Ralph-style iterative execution
Single focused task	`executing-plans`	Direct plan execution

Invoke the chosen skill and pass the plan document path.

Anti-Patterns / Common Mistakes

Anti-Pattern	Why It Fails	Correct Approach
"This is too simple to plan"	Simple tasks have unexamined assumptions	Plan anyway — the plan can be short
"I already know the approach"	Your approach may conflict with project patterns	Document it and get approval
"The user wants it fast"	Bad code is slower than planned code	Planning prevents rework
"It's just a bug fix"	Bug fixes need root cause analysis	Plan the fix, not just the patch
"I'll plan as I go"	That is improvising, not planning	Plan first, execute second
Asking 5 questions at once	Overwhelms the user, gets vague answers	One question per message
Proposing only 1 approach	No trade-off analysis, may miss better options	Always propose 2-3 approaches
Vague file references	"Update the tests" — which tests?	Exact file paths always
Tasks that take 30+ minutes	Too large to track and verify	Break into 2-5 minute tasks
Starting code before approval	Wastes effort if direction changes	Wait for explicit "yes"

Anti-Rationalization Guards

<HARD-GATE> Do NOT write any code, create any files, or take any implementation action until: 1. You have asked clarifying questions and understood the requirements 2. You have proposed approaches with trade-offs 3. The user has explicitly approved the plan

This applies to EVERY task regardless of perceived simplicity. </HARD-GATE>

Iron Law: NO CODE WITHOUT AN APPROVED PLAN. No exceptions. No "just this small thing." No "it's obvious."

If you catch yourself thinking any of the following, STOP immediately:

"Let me just quickly..." — No. Plan first.
"This doesn't need a full plan..." — Yes it does. The plan can be brief.
"I'll document it after..." — No. Document before.

Subagent Dispatch Opportunities

Task Pattern	Dispatch To	When
Independent research tasks during planning	`Agent` tool with `subagent_type="Explore"`	When gathering context from multiple codebase areas
Plan validation across architecture layers	`Agent` tool dispatching `planner` agent	When plan covers multiple system boundaries
After plan approval, independent implementation tasks	`Agent` tool (multiple parallel, per `dispatching-parallel-agents` skill)	When plan steps have no dependencies between them

Follow the

dispatching-parallel-agents

skill protocol when dispatching.

Integration Points

Skill	Relationship	When
`brainstorming`	Upstream — provides design context	Planning follows brainstorming
`task-management`	Downstream — receives approved plan	Standard execution path
`executing-plans`	Downstream — executes plan directly	Single-task execution
`subagent-driven-development`	Downstream — parallel execution	Large independent task sets
`autonomous-loop`	Downstream — iterative execution	Ralph-style sessions
`self-learning`	Bidirectional — informs and learns from planning	Context loading and pattern storage
`verification-before-completion`	Downstream — verifies plan completeness	Before claiming plan is done
`task-decomposition`	Complementary — provides WBS for complex plans	When plan needs hierarchical breakdown

Concrete Examples

Example: Small Bug Fix Plan

markdown

# Fix: Login button disabled state not clearing

**Goal:** Fix login button remaining disabled after failed login attempt
**Architecture:** State management bug in LoginForm component
**Approach:** Reset `isSubmitting` state in the catch block of handleSubmit

### Task 1: Write failing test
**Files:** Test: `tests/components/LoginForm.test.tsx`
**Steps:** Write test that submits invalid credentials and verifies button re-enables
**Verification:** `npm test -- --grep "re-enables button after failed login"`

### Task 2: Fix the bug
**Files:** Modify: `src/components/LoginForm.tsx`
**Steps:** Add `setIsSubmitting(false)` to catch block in handleSubmit
**Verification:** `npm test -- --grep "LoginForm"` — all pass

Example: Transition Command

After plan approval:

Plan approved and saved to docs/plans/2026-03-15-login-fix.md.
Invoking task-management skill to begin tracked execution.

Verification Gate

Before claiming the plan is complete, verify:

IDENTIFY: Plan document exists at
```
docs/plans/
```
RUN: Review plan for completeness against quality checklist
READ: Verify all sections are filled with specific details
VERIFY: User has explicitly approved
CLAIM: Only then transition to implementation

Key Principles

DRY — Do not repeat yourself
YAGNI — Do not build what is not needed yet
TDD — Write tests first when applicable
Frequent commits — Small, atomic commits after each task
Exact paths — Always specify exact file paths in the plan

Skill Type

RIGID — Follow this process exactly for every implementation task. The phases are sequential and non-negotiable. No code without an approved plan.

planning

NPX Install

Tags

SKILL.md Content