Thorough Planning
Overview
Planning without success criteria is hoping. Before writing any code, you must know:
- •How will we know it worked? (Success criteria)
- •How will we know we're on track? (Feedback loops)
Core principle: Define "done" before starting. Measurable outcomes before implementation.
When to Use
Use when:
- •User says "plan", "design", "implement", "build", "refactor"
- •Task requires 3+ steps or multiple files
- •Success/done criteria are unclear
- •You don't know how to verify progress
Don't use when:
- •Single-line fix with clear error message
- •User provides explicit success criteria already
- •Trivial change (rename, format, small edit)
Quick Reference
| Situation | Action |
|---|---|
| "Build X feature" | Define success criteria FIRST |
| Multi-step task | Establish feedback loop |
| "Just make it work" | Clarify what "work" means measurably |
| Unclear requirements | Ask user (don't assume) |
| "Simple" task | Simple tasks get simple criteria - still need them |
Surface Assumptions First
Before proceeding, state explicitly:
- •Interpretation: If multiple ways to read the request, present them - don't pick silently
- •Approach: If a simpler approach exists, say so. Push back when warranted.
- •Unknowns: If something is unclear, stop. Name what's confusing. Ask.
Template:
My assumptions: - User wants: [interpretation] - Tech approach: [framework/pattern assumed] - Scope: [what's included/excluded] If any assumption is wrong, let me know before I proceed.
The Pattern
1. Define Success Criteria (MANDATORY)
Before ANY implementation, answer explicitly:
| Question | Template |
|---|---|
| What does "done" look like? | "Task complete when [observable outcome]" |
| How will user verify? | "User can verify by [action] and seeing [result]" |
| What's the acceptance test? | "If [condition] then [expected behavior]" |
If you can't answer these, ASK THE USER. Do not proceed without at least one measurable criterion.
Transform Vague Tasks to Verifiable Goals
| Instead of... | Transform to... |
|---|---|
| "Add validation" | "Write tests for invalid inputs, then make them pass" |
| "Fix the bug" | "Write a test that reproduces it, then make it pass" |
| "Refactor X" | "Ensure tests pass before and after" |
| "Make it faster" | "Benchmark before/after, target: X% improvement" |
2. Define Feedback Loops (MANDATORY)
How will you know you're on track DURING implementation?
| Loop Type | When to Use |
|---|---|
| Test-driven | New feature/bug - write failing test first |
| Incremental | Multi-step - verify each step before next |
| Build check | Code changes - run build after each file |
| Manual verification | UI changes - preview at each stage |
At least one feedback loop required before starting.
3. Research Phase
Prefer researching before coding. Use subagents for:
- •Exploring multiple files in parallel
- •Searching documentation
- •Understanding existing patterns
Discover available tools (MANDATORY): Invoke the context-suggest skill to discover all available skills, agents, commands, and MCP tools for this project. This is required - the discovered tools will be displayed in the Tools Summary (Step 7).
For complex plans: When breaking down intricate problems, use the sequential_thinking MCP tool to decompose step by step with revision support.
4. Handle Uncertainty
| Uncertainty Type | Action |
|---|---|
| Requirements unclear | ASK USER - do not guess |
| Technical unknown | Use systematic-debugging skill |
| Multiple approaches | Ask user, then document with decision-journal |
Default: When uncertain, ask user.
Document decisions: When choosing between approaches, use the decision-journal skill to capture context, options, rationale, and trade-offs in the plan file.
5. Surface Quality Considerations (Advisory)
Use the code-quality-gate skill to surface relevant quality considerations before implementation:
| Category | Consider |
|---|---|
| Simplicity | Minimum code, no speculative features |
| Change Scope | Touch only what's needed, match existing style |
| Architecture | Pattern consistency, separation of concerns |
| Correctness | Edge cases, error handling, type safety |
| Readability | Naming, complexity, single responsibility |
Not all apply to every task. Identify which are relevant and note them in the plan.
6. Document Brief Plan
## Assumptions - User wants: [interpretation] - Tech approach: [framework/pattern assumed] - Scope: [what's included/excluded] ## Success Criteria - [ ] [Criterion 1 - observable/testable] ## Feedback Loop - [How you'll verify during implementation] ## Decisions ### [Decision Title] **Chose** [X] **over** [Y] **because** [reason]. **Trade-off:** [cost]. ## Quality Considerations - **Simplicity:** [minimum code, no speculative features] - **Change Scope:** [touch only what's needed] - **Architecture:** [relevant considerations] - **Correctness:** [edge cases, error handling] - **Readability:** [naming, complexity notes] ## Steps (with inline verification) 1. [Step] → verify: [how you'll know it worked]
7. Display Tools Summary (MANDATORY)
After completing the plan, display a prominent summary of all tools that will be used.
Invoke the context-suggest skill to discover available components, then output:
## 🛠️ Tools & Skills for This Plan (TOOLS_SKILLS_SUMMARY) ### 🎯 Skills - **[skill-name]**: [when it will be used in the plan] ### 🤖 Agents - **[agent-name]**: [when it will be used in the plan] ### ⌨️ Commands - **/[command]**: [when it will be used in the plan] ### 🔌 MCP Tools - **[mcp-name]**: [when it will be used in the plan]
Rules:
- •Only list components that ARE actually used in the plan steps
- •Each entry must reference WHEN in the plan it's used
- •Skip empty categories (don't show "Agents" section if none are used)
- •This summary is the LAST thing shown before implementation begins
Common Mistakes
| Mistake | Fix |
|---|---|
| "It's simple, no need to plan" | Simple tasks = simple criteria. 30 seconds. Do it. |
| "I asked questions" | Questions ≠ success criteria. Frame them explicitly. |
| "I'll know done when I see it" | That's discovery, not planning. Define upfront. |
| "User wants speed" | Fast + wrong = slower than planned + right |
| "Research first" | Know what "done" looks like BEFORE researching |
| Exploring before defining "done" | Define what you're looking FOR before searching |
Extended Content
- •references/question-bank.md - Question templates by category
- •references/subagent-prompts.md - Research subagent prompts
- •references/examples.md - Good vs bad planning examples
Related Skills
- •decision-journal - Capture architectural decisions with context and rationale
- •code-quality-gate - Architecture, correctness, and readability checklist
Before Exiting Plan Mode
Verify: Tools Summary section displayed. If missing, invoke /context-suggest first.