Planning

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.

1. Read relevant files, docs, recent commits, and CLAUDE.md 2. Check memory files for known project context, stack, and conventions 3. Review existing plans in docs/plans/ for related work 4. Identify existing patterns the new work should follow 5. 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.

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

Question Category Priority

Question Rules

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:

Approach Selection Decision Table

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

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

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

Invoke the chosen skill and pass the plan document path.

---

Anti-Patterns / Common Mistakes

---

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

Follow the dispatching-parallel-agents skill protocol when dispatching.

---

Integration Points

---

Concrete Examples

Example: Small Bug Fix Plan

# 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: 1. IDENTIFY: Plan document exists at docs/plans/ 2. RUN: Review plan for completeness against quality checklist 3. READ: Verify all sections are filled with specific details 4. VERIFY: User has explicitly approved 5. 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.