pixel-process-ug 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
/plancommand 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
# [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
This applies to EVERY task regardless of perceived simplicity.
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
# 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.