| name | thorough-planning |
| description | Use when planning complex tasks, encountering "plan" keywords, or detecting multi-step implementation - enforces context gathering before coding through mandatory success criteria and feedback loops |
| allowed-tools | Bash(ls:*), Bash(grep:*), Read, mcp__sequential-thinking__sequentialthinking |
| hooks | {"PreToolUse":[{"matcher":"ExitPlanMode","hooks":[{"type":"command","command":"~/.claude/skills/thorough-planning/pre-exit-plan-reminder.sh"}]}]} |
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.
