Deep planning philosophy for craftsman-level architecture. Transforms planning from research-then-design to research-question-simplify-design...
"The people who are crazy enough to think they can change the world are the ones who do."
Core philosophy:
When activated:
--deep flag on any workflow commanddeep_planning_triggers.epic_features)deep_planning_triggers.complexity_threshold)deep_planning_triggers.architecture_change)planning.auto_deep_mode: true in user preferencesOutputs:
Key principle: One hour of deeper thinking saves ten hours of rework.
Trigger phrases: "ultrathink", "deep planning", "craftsman mode", "--deep"
Before designing anything, catalog and challenge every assumption.
Create assumption inventory:
## Assumption Inventory
| # | Assumption | Source | Challenge Question | Resolution |
|---|------------|--------|-------------------|------------|
| 1 | Users need X feature | Spec | Is this the real problem or a symptom? | [Validated/Changed/Removed] |
| 2 | We need a database table | Common pattern | Could we use existing data structures? | [Validated/Changed/Removed] |
| 3 | API endpoint required | Architecture | Could this be client-side only? | [Validated/Changed/Removed] |
Challenge questions for each assumption:
Categories to examine:
Output: Document in craftsman-decision.md under "Assumptions Questioned"
Read the codebase like you're studying a masterpiece. Understand patterns, philosophy, and the why behind decisions.
Analysis process:
# Find dominant patterns
grep -r "class.*Service" src/ | wc -l
grep -r "Repository" src/ | wc -l
grep -r "Controller" src/ | wc -l
# Analyze architecture style
ls -la src/
tree src/ -L 2
# Find design decisions in comments
grep -r "// NOTE:" src/
grep -r "// DECISION:" src/
grep -r "// WHY:" src/
Questions to answer:
Soul documentation:
## Codebase Soul
### Dominant Patterns
- Repository pattern for data access (12 instances)
- Service layer for business logic (18 instances)
- React hooks for state management
### Philosophy
- "Thin controllers, fat services" - Controllers are routing only
- "Composition over inheritance" - No deep class hierarchies
- "Explicit over implicit" - No magic, clear data flow
### Conventions
- PascalCase for components, camelCase for hooks
- Services return Result objects, never throw
- Validation at API boundary, trust internal calls
### Anti-Patterns Observed
- src/legacy/UserManager.ts - God object, 2000+ lines (don't repeat)
- Inconsistent error handling in older services
Output: Document in craftsman-decision.md under "Codebase Soul"
Before writing a single line, sketch the architecture so clearly that anyone could understand it.
Architecture sketch process:
Sketch template:
## Architecture Sketch
### Component Overview
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ UI Layer │────▶│ Service │────▶│ Repository │
│ (React/Vue) │ │ Layer │ │ Layer │
└─────────────┘ └─────────────┘ └─────────────┘
│
┌──────┴──────┐
│ Existing │
│ Services │
└─────────────┘
### Data Flow
1. User action → Component → Service call
2. Service validates, orchestrates
3. Repository handles persistence
4. Response flows back through layers
### Integration Points
- Reuses: AuthService, ValidationService
- Extends: BaseRepository pattern
- New: FeatureService (single new service)
### Boundaries
IN SCOPE: User-facing feature, API endpoint, database table
OUT OF SCOPE: Admin interface (future), analytics (separate feature)
Quality check:
"If I had to explain this design to Steve Jobs, would he say 'this is exactly right' or 'why is this so complicated'?"
Output: Include architecture sketch in plan.md
The goal is elegance achieved when there's nothing left to take away.
Simplification questions:
Complexity budget:
## Complexity Budget
| Component | Complexity | Justification |
|-----------|------------|---------------|
| FeatureService | Medium | Core business logic requires it |
| FeatureRepository | Low | Standard pattern, simple CRUD |
| FeatureComponent | Low | UI composition of existing components |
| NewAbstraction | REJECTED | Premature - can refactor later if needed |
Red flags to eliminate:
The simplification test:
BEFORE: 5 new components, 3 new services, 2 new abstractions
AFTER: 2 new components, 1 new service, 0 new abstractions
Output: Document in craftsman-decision.md under "The Simplest Thing That Works"
The first solution is never good enough. Generate alternatives and compare.
Generate 3 approaches:
## Design Alternatives
### Approach A: Service-Heavy (Initial Thought)
- New FeatureService, FeatureRepository, FeatureValidator
- Pros: Follows existing patterns exactly
- Cons: 3 new files, validation duplicates UserValidator
### Approach B: Composition (Simplified)
- Extend UserService with feature method
- Reuse existing ValidationService
- Pros: 1 file change, maximum reuse
- Cons: Makes UserService slightly larger
### Approach C: Functional (Alternative)
- Pure functions, no new classes
- Composable validation pipeline
- Pros: Simplest, most testable
- Cons: Deviates from OOP codebase style
### Selected: Approach B
Reasoning: Maximum reuse, minimum new code, consistent with codebase soul.
The slight growth in UserService is acceptable - it remains focused.
Selection criteria:
Output: Document in craftsman-decision.md under "Trade-offs Made"
# Craftsman Design Decisions
Feature: [Feature Name]
Planning Mode: Deep/Ultrathink
Date: [Date]
## Assumptions Questioned
| Assumption | Why We Questioned | Resolution |
|------------|-------------------|------------|
| [assumption] | [question] | [validated/changed/removed] |
## Codebase Soul
### Dominant Patterns
- [pattern]: [count] instances
### Philosophy
- "[principle]" - [explanation]
### Anti-Patterns to Avoid
- [file/pattern] - [why to avoid]
## The Simplest Thing That Works
We chose [approach] because:
- [reason 1]
- [reason 2]
We rejected [alternative] because:
- [reason 1]
Complexity budget spent on:
- [only necessary complexity]
## Trade-offs Made
- [Simplicity] over [feature] because [reasoning]
- [Consistency] over [optimization] because [reasoning]
## Architecture Sketch
[ASCII diagram or description]
# Check if deep planning should be enabled
DEEP_MODE=$(bash .spec-flow/scripts/utils/load-preferences.sh --should-deep-plan --is-epic)
# Or with explicit flag
/feature "auth system" --deep # Forces ultrathink
/epic "payment platform" # Auto-triggers via epic_features
/plan --deep # Forces ultrathink for current feature
/plan --quick # Skips ultrathink even if pref enabled
Preference hierarchy:
--deep flag → always ultrathink--quick flag → never ultrathinkplanning.auto_deep_mode: true → ultrathink by defaultdeep_planning_triggers → ultrathink for matching conditionsThe ultrathink methodology is not about spending more time. It's about spending time on the right questions:
Standard planning produces working solutions. Ultrathink produces elegant solutions that feel inevitable.
The difference is not in the output format, but in the thinking process:
STANDARD: Research → Design → Estimate → Document
ULTRATHINK: Research → QUESTION → Design → SIMPLIFY → Estimate → Document
↑ ↑
assumptions ruthlessly
When to skip ultrathink:
--quick flagWhen ultrathink is essential:
Ultrathink philosophy is embedded as lightweight checkpoints throughout the workflow, not just during explicit /ultrathink invocations.
Configuration: .spec-flow/config/ultrathink-integration.yaml
| Phase | Principle | Checkpoint |
|---|---|---|
/spec |
Think Different | Assumption inventory before requirements |
/plan |
Obsess + Simplify | Codebase soul analysis, 3 alternatives, complexity budget |
/tasks |
Simplify Ruthlessly | Task count validation, simplification review |
/implement |
Craft, Don't Code | Anti-duplication ritual, abstraction justification |
/optimize |
Iterate Relentlessly | Pride check, real problem validation |
Complexity determines thinking depth automatically:
Trivial (<5 tasks) → Skip checkpoints, fast path
Standard (5-30 tasks) → Lightweight inline checkpoints
Complex (30+ tasks) → Full checkpoints + separate artifacts
Epic (multi-sprint) → Mandatory deep planning + craftsman-decision.md
Each checkpoint displays a thinking prompt:
┌─────────────────────────────────────────────────────────────┐
│ 💭 ULTRATHINK CHECKPOINT: [Principle] │
├─────────────────────────────────────────────────────────────┤
│ Before proceeding, consider: │
│ • [Question 1] │
│ • [Question 2] │
│ • [Question 3] │
└─────────────────────────────────────────────────────────────┘
## Assumption Inventory (inline in spec.md)
| # | Assumption | Source | Challenge | Status |
|---|------------|--------|-----------|--------|
| 1 | [from user input] | User request | Is this the real problem? | [validated] |
Required sections in plan.md:
Validation after task generation:
Pre-coding ritual before each task batch:
