feat(04-02): 70% context reduction for plan-phase (scope-estimation 74%, plan-phase.md 66%)
- scope-estimation.md: 451 → 115 lines (removed ASCII art, collapsed anti-patterns) - plan-phase.md workflow: 864 → 290 lines (condensed discovery tree, removed verbose examples) - Total Phase 4 context reduction: 101KB → 30KB (exceeds 37% target)
This commit is contained in:
Lex Christopherson
@@ -1,447 +1,111 @@
|
||||
<scope_estimation>
|
||||
Plans must maintain consistent quality from first task to last. This requires understanding the **quality degradation curve** and splitting aggressively to stay in the peak quality zone.
|
||||
Plans must maintain consistent quality from first task to last. This requires understanding quality degradation and splitting aggressively.
|
||||
|
||||
<quality_degradation_curve>
|
||||
<quality_insight>
|
||||
Claude degrades when it *perceives* context pressure and enters "completion mode."
|
||||
|
||||
**Critical insight:** Claude doesn't degrade at arbitrary percentages - it degrades when it *perceives* context pressure and enters "completion mode."
|
||||
| Context Usage | Quality | Claude's State |
|
||||
|---------------|---------|----------------|
|
||||
| 0-30% | PEAK | Thorough, comprehensive |
|
||||
| 30-50% | GOOD | Confident, solid work |
|
||||
| 50-70% | DEGRADING | Efficiency mode begins |
|
||||
| 70%+ | POOR | Rushed, minimal |
|
||||
|
||||
```
|
||||
Context Usage │ Quality Level │ Claude's Mental State
|
||||
─────────────────────────────────────────────────────────
|
||||
0-30% │ ████████ PEAK │ "I can be thorough and comprehensive"
|
||||
│ │ No anxiety, full detail, best work
|
||||
**The 40-50% inflection point:** Claude sees context mounting and thinks "I'd better conserve now." Result: "I'll complete the remaining tasks more concisely" = quality crash.
|
||||
|
||||
30-50% │ ██████ GOOD │ "Still have room, maintaining quality"
|
||||
│ │ Engaged, confident, solid work
|
||||
|
||||
50-70% │ ███ DEGRADING │ "Getting tight, need to be efficient"
|
||||
│ │ Efficiency mode, compression begins
|
||||
|
||||
70%+ │ █ POOR │ "Running out, must finish quickly"
|
||||
│ │ Self-lobotomization, rushed, minimal
|
||||
```
|
||||
|
||||
**The 40-50% inflection point:**
|
||||
|
||||
This is where quality breaks. Claude sees context mounting and thinks "I'd better conserve now or I won't finish." Result: The classic mid-execution statement "I'll complete the remaining tasks more concisely" = quality crash.
|
||||
|
||||
**The fundamental rule:** Stop BEFORE quality degrades, not at context limit.
|
||||
</quality_degradation_curve>
|
||||
**The rule:** Stop BEFORE quality degrades, not at context limit.
|
||||
</quality_insight>
|
||||
|
||||
<context_target>
|
||||
|
||||
**Plans should complete within ~50% of context usage.**
|
||||
|
||||
Why 50% not 80%?
|
||||
- Huge safety buffer
|
||||
- No context anxiety possible
|
||||
- Quality maintained from start to finish
|
||||
- Quality maintained start to finish
|
||||
- Room for unexpected complexity
|
||||
- Space for iteration and fixes
|
||||
|
||||
**If you target 80%, you're planning for failure.** By the time you hit 80%, you've already spent 40% in degradation mode.
|
||||
- If you target 80%, you've already spent 40% in degradation mode
|
||||
</context_target>
|
||||
|
||||
<task_rule>
|
||||
**Each plan: 2-3 tasks maximum. Stay under 50% context.**
|
||||
|
||||
**Each plan should contain 2-3 tasks maximum. Context usage matters more than task count.**
|
||||
|
||||
**The real measure: Stay under 50% context usage.**
|
||||
|
||||
Task count is a proxy for context. Adjust based on task complexity:
|
||||
|
||||
**Simple tasks (CRUD, config, basic features):**
|
||||
- 3 tasks is fine
|
||||
- Each burns ~10-15% context
|
||||
- Total: ~30-45% → Safe
|
||||
|
||||
**Complex tasks (auth, payments, architecture, integrations):**
|
||||
- Stick to 2 tasks
|
||||
- Each burns ~20-30% context
|
||||
- Total: ~40-50% → At limit
|
||||
|
||||
**Very complex tasks (migrations, major refactors, novel patterns):**
|
||||
- Consider 1-2 tasks only
|
||||
- Each can burn 30-40% context
|
||||
- Splitting to 1 task/plan is valid for high complexity
|
||||
|
||||
**Context estimation by task type:**
|
||||
|
||||
**Task 1 (0-15% context for simple, 0-30% for complex):**
|
||||
- Fresh context
|
||||
- Peak quality
|
||||
- Comprehensive implementation
|
||||
- Full testing
|
||||
|
||||
**Task 2 (15-35% context for simple, 30-50% for complex):**
|
||||
- Still good quality
|
||||
- Context pressure manageable
|
||||
- Natural stopping point for complex work
|
||||
|
||||
**Task 3 (35-50% context for simple only):**
|
||||
- Only include for simple tasks
|
||||
- Skip for complex work
|
||||
- Better to split complex work at 2 tasks
|
||||
|
||||
**Task 4+ (50%+ context):**
|
||||
- NEVER do this
|
||||
- Quality guaranteed to degrade
|
||||
- Should have split earlier
|
||||
| Task Complexity | Tasks/Plan | Context/Task | Total |
|
||||
|-----------------|------------|--------------|-------|
|
||||
| Simple (CRUD, config) | 3 | ~10-15% | ~30-45% |
|
||||
| Complex (auth, payments) | 2 | ~20-30% | ~40-50% |
|
||||
| Very complex (migrations, refactors) | 1-2 | ~30-40% | ~30-50% |
|
||||
|
||||
**When in doubt: Default to 2 tasks.** Better to have an extra plan than degraded quality.
|
||||
|
||||
**The principle:** Each plan completes within 50% context. Task count is flexible based on complexity.
|
||||
</task_rule>
|
||||
|
||||
<split_signals>
|
||||
|
||||
<always_split>
|
||||
|
||||
**1. More than 3 tasks**
|
||||
- Even if tasks seem small
|
||||
- Each additional task increases degradation risk
|
||||
- Split into logical groups of 2-3
|
||||
|
||||
**2. Multiple subsystems**
|
||||
```
|
||||
❌ Bad (1 plan):
|
||||
- Database schema (3 files)
|
||||
- API routes (5 files)
|
||||
- UI components (8 files)
|
||||
Total: 16 files, 1 plan → guaranteed degradation
|
||||
|
||||
✅ Good (3 plans):
|
||||
- 01-01-PLAN.md: Database schema (3 files, 2 tasks)
|
||||
- 01-02-PLAN.md: API routes (5 files, 3 tasks)
|
||||
- 01-03-PLAN.md: UI components (8 files, 3 tasks)
|
||||
Total: 16 files, 3 plans → consistent quality
|
||||
```
|
||||
|
||||
**3. Any task with >5 file modifications**
|
||||
- Large tasks burn context fast
|
||||
- Split by file groups or logical units
|
||||
- Better: 3 plans of 2 files each vs 1 plan of 6 files
|
||||
|
||||
**4. Checkpoint + implementation work**
|
||||
- Checkpoints require user interaction (context preserved)
|
||||
- Implementation after checkpoint should be separate plan
|
||||
|
||||
✅ Good split:
|
||||
- 02-01-PLAN.md: Setup (checkpoint: decision on auth provider)
|
||||
- 02-02-PLAN.md: Implement chosen auth solution
|
||||
|
||||
**5. Discovery + implementation**
|
||||
- Discovery produces DISCOVERY.md (separate plan)
|
||||
- Implementation consumes DISCOVERY.md (separate plan)
|
||||
- Clear boundary, clean handoff
|
||||
- **More than 3 tasks** - Even if tasks seem small
|
||||
- **Multiple subsystems** - DB + API + UI = separate plans
|
||||
- **Any task with >5 file modifications** - Split by file groups
|
||||
- **Checkpoint + implementation work** - Checkpoints in one plan, implementation after in separate plan
|
||||
- **Discovery + implementation** - DISCOVERY.md in one plan, implementation in another
|
||||
</always_split>
|
||||
|
||||
<consider_splitting>
|
||||
|
||||
**1. Estimated >5 files modified total**
|
||||
- Context from reading existing code
|
||||
- Context from diffs
|
||||
- Context from responses
|
||||
- Adds up faster than expected
|
||||
|
||||
**2. Complex domains (auth, payments, data modeling)**
|
||||
- These require careful thinking
|
||||
- Burns more context per task than simple CRUD
|
||||
- Split more aggressively
|
||||
|
||||
**3. Any uncertainty about approach**
|
||||
- "Figure out X" phase separate from "implement X" phase
|
||||
- Don't mix exploration and implementation
|
||||
|
||||
**4. Natural semantic boundaries**
|
||||
- Setup → Core → Features
|
||||
- Backend → Frontend
|
||||
- Configuration → Implementation → Testing
|
||||
- Estimated >5 files modified total
|
||||
- Complex domains (auth, payments, data modeling)
|
||||
- Any uncertainty about approach
|
||||
- Natural semantic boundaries (Setup -> Core -> Features)
|
||||
</consider_splitting>
|
||||
</split_signals>
|
||||
|
||||
<splitting_strategies>
|
||||
**By subsystem:** Auth → 01: DB models, 02: API routes, 03: Protected routes, 04: UI components
|
||||
|
||||
<by_subsystem>
|
||||
**By dependency:** Payments → 01: Stripe setup, 02: Subscription logic, 03: Frontend integration
|
||||
|
||||
**Phase:** "Authentication System"
|
||||
**By complexity:** Dashboard → 01: Layout shell, 02: Data fetching, 03: Visualization
|
||||
|
||||
**Split:**
|
||||
```
|
||||
- 03-01-PLAN.md: Database models (User, Session tables + relations)
|
||||
- 03-02-PLAN.md: Auth API (register, login, logout endpoints)
|
||||
- 03-03-PLAN.md: Protected routes (middleware, JWT validation)
|
||||
- 03-04-PLAN.md: UI components (login form, registration form)
|
||||
```
|
||||
|
||||
Each plan: 2-3 tasks, single subsystem, clean commits.
|
||||
</by_subsystem>
|
||||
|
||||
<by_dependency>
|
||||
|
||||
**Phase:** "Payment Integration"
|
||||
|
||||
**Split:**
|
||||
```
|
||||
- 04-01-PLAN.md: Stripe setup (webhook endpoints via API, env vars, test mode)
|
||||
- 04-02-PLAN.md: Subscription logic (plans, checkout, customer portal)
|
||||
- 04-03-PLAN.md: Frontend integration (pricing page, payment flow)
|
||||
```
|
||||
|
||||
Later plans depend on earlier completion. Sequential execution, fresh context each time.
|
||||
</by_dependency>
|
||||
|
||||
<by_complexity>
|
||||
|
||||
**Phase:** "Dashboard Buildout"
|
||||
|
||||
**Split:**
|
||||
```
|
||||
- 05-01-PLAN.md: Layout shell (simple: sidebar, header, routing)
|
||||
- 05-02-PLAN.md: Data fetching (moderate: TanStack Query setup, API integration)
|
||||
- 05-03-PLAN.md: Data visualization (complex: charts, tables, real-time updates)
|
||||
```
|
||||
|
||||
Complex work gets its own plan with full context budget.
|
||||
</by_complexity>
|
||||
|
||||
<by_verification_points>
|
||||
|
||||
**Phase:** "Deployment Pipeline"
|
||||
|
||||
**Split:**
|
||||
```
|
||||
- 06-01-PLAN.md: Vercel setup (deploy via CLI, configure domains)
|
||||
→ Ends with checkpoint:human-verify "check xyz.vercel.app loads"
|
||||
|
||||
- 06-02-PLAN.md: Environment config (secrets via CLI, env vars)
|
||||
→ Autonomous (no checkpoints) → subagent execution
|
||||
|
||||
- 06-03-PLAN.md: CI/CD (GitHub Actions, preview deploys)
|
||||
→ Ends with checkpoint:human-verify "check PR preview works"
|
||||
```
|
||||
|
||||
Verification checkpoints create natural boundaries. Autonomous plans between checkpoints execute via subagent with fresh context.
|
||||
</by_verification_points>
|
||||
**By verification:** Deploy → 01: Vercel setup (checkpoint), 02: Env config (auto), 03: CI/CD (checkpoint)
|
||||
</splitting_strategies>
|
||||
|
||||
<autonomous_vs_interactive>
|
||||
|
||||
**Critical optimization:** Plans without checkpoints don't need main context.
|
||||
|
||||
<autonomous_plans>
|
||||
- Contains only `type="auto"` tasks
|
||||
- No user interaction needed
|
||||
- **Execute via subagent with fresh 200k context**
|
||||
- Impossible to degrade (always starts at 0%)
|
||||
- Creates SUMMARY, commits, reports back
|
||||
- Can run in parallel (multiple subagents)
|
||||
</autonomous_plans>
|
||||
|
||||
<interactive_plans>
|
||||
- Contains `checkpoint:human-verify` or `checkpoint:decision` tasks
|
||||
- Requires user interaction
|
||||
- Must execute in main context
|
||||
- Still target 50% context (2-3 tasks)
|
||||
|
||||
**Planning guidance:** If splitting a phase, try to:
|
||||
- Group autonomous work together (→ subagent)
|
||||
- Separate interactive work (→ main context)
|
||||
- Maximize autonomous plans (more fresh contexts)
|
||||
|
||||
Example:
|
||||
```
|
||||
Phase: Feature X
|
||||
- 07-01-PLAN.md: Backend (autonomous) → subagent
|
||||
- 07-02-PLAN.md: Frontend (autonomous) → subagent
|
||||
- 07-03-PLAN.md: Integration test (has checkpoint:human-verify) → main context
|
||||
```
|
||||
|
||||
Two fresh contexts, one interactive verification. Perfect.
|
||||
</interactive_plans>
|
||||
</autonomous_vs_interactive>
|
||||
|
||||
<anti_patterns>
|
||||
|
||||
<antipattern_comprehensive>
|
||||
|
||||
**Bad - Comprehensive plan:**
|
||||
```
|
||||
Plan: "Complete Authentication System"
|
||||
Tasks:
|
||||
1. Database models
|
||||
2. Migration files
|
||||
3. Auth API endpoints
|
||||
4. JWT utilities
|
||||
5. Protected route middleware
|
||||
6. Password hashing
|
||||
7. Login form component
|
||||
8. Registration form component
|
||||
|
||||
Result: 8 tasks, 80%+ context, degradation at task 4-5
|
||||
Tasks: 8 (models, migrations, API, JWT, middleware, hashing, login form, register form)
|
||||
Result: Task 1-3 good, Task 4-5 degrading, Task 6-8 rushed
|
||||
```
|
||||
|
||||
**Why this fails:**
|
||||
- Task 1-3: Good quality
|
||||
- Task 4-5: "I'll do these concisely" = degradation begins
|
||||
- Task 6-8: Rushed, minimal, poor quality
|
||||
</antipattern_comprehensive>
|
||||
|
||||
<pattern_atomic>
|
||||
|
||||
**Good - Atomic plans:**
|
||||
```
|
||||
Split into 4 plans:
|
||||
|
||||
Plan 1: "Auth Database Models" (2 tasks)
|
||||
- Database schema (User, Session)
|
||||
- Migration files
|
||||
|
||||
Plan 2: "Auth API Core" (3 tasks)
|
||||
- Register endpoint
|
||||
- Login endpoint
|
||||
- JWT utilities
|
||||
|
||||
Plan 3: "Auth API Protection" (2 tasks)
|
||||
- Protected route middleware
|
||||
- Logout endpoint
|
||||
|
||||
Plan 4: "Auth UI Components" (2 tasks)
|
||||
- Login form
|
||||
- Registration form
|
||||
Each: 30-40% context, peak quality, focused commits
|
||||
```
|
||||
|
||||
**Why this succeeds:**
|
||||
- Each plan: 2-3 tasks, 30-40% context
|
||||
- All tasks: Peak quality throughout
|
||||
- Git history: 4 focused commits
|
||||
- Easy to verify each piece
|
||||
- Rollback is surgical
|
||||
</pattern_atomic>
|
||||
|
||||
<antipattern_efficiency_trap>
|
||||
|
||||
```
|
||||
Thinking: "These tasks are small, let's do 6 to be efficient"
|
||||
|
||||
Result: Task 1-2 are good, task 3-4 begin degrading, task 5-6 are rushed
|
||||
```
|
||||
|
||||
**Why this fails:** You're optimizing for fewer plans, not quality. The "efficiency" is false - poor quality requires more rework.
|
||||
</antipattern_efficiency_trap>
|
||||
|
||||
<pattern_quality_first>
|
||||
|
||||
```
|
||||
Thinking: "These tasks are small, but let's do 2-3 to guarantee quality"
|
||||
|
||||
Result: All tasks peak quality, clean commits, no rework needed
|
||||
```
|
||||
|
||||
**Why this succeeds:** You optimize for quality, which is true efficiency. No rework = faster overall.
|
||||
</pattern_quality_first>
|
||||
</anti_patterns>
|
||||
|
||||
<estimating_context>
|
||||
| Files Modified | Context Impact |
|
||||
|----------------|----------------|
|
||||
| 0-3 files | ~10-15% (small) |
|
||||
| 4-6 files | ~20-30% (medium) |
|
||||
| 7+ files | ~40%+ (large - split) |
|
||||
|
||||
**Rough heuristics for plan size:**
|
||||
| Complexity | Context/Task |
|
||||
|------------|--------------|
|
||||
| Simple CRUD | ~15% |
|
||||
| Business logic | ~25% |
|
||||
| Complex algorithms | ~40% |
|
||||
| Domain modeling | ~35% |
|
||||
|
||||
<file_counts>
|
||||
- 0-3 files modified: Small task (~10-15% context)
|
||||
- 4-6 files modified: Medium task (~20-30% context)
|
||||
- 7+ files modified: Large task (~40%+ context) - split this
|
||||
</file_counts>
|
||||
|
||||
<complexity>
|
||||
- Simple CRUD: ~15% per task
|
||||
- Business logic: ~25% per task
|
||||
- Complex algorithms: ~40% per task
|
||||
- Domain modeling: ~35% per task
|
||||
</complexity>
|
||||
|
||||
<two_task_plan>
|
||||
- 2 simple tasks: ~30% total ✅ Plenty of room
|
||||
- 2 medium tasks: ~50% total ✅ At target
|
||||
- 2 complex tasks: ~80% total ❌ Too tight, split
|
||||
</two_task_plan>
|
||||
|
||||
<three_task_plan>
|
||||
- 3 simple tasks: ~45% total ✅ Good
|
||||
- 3 medium tasks: ~75% total ⚠️ Pushing it
|
||||
- 3 complex tasks: 120% total ❌ Impossible, split
|
||||
|
||||
**Conservative principle:** When in doubt, split. Better to have an extra plan than degraded quality.
|
||||
</three_task_plan>
|
||||
**2 tasks:** Simple ~30%, Medium ~50%, Complex ~80% (split)
|
||||
**3 tasks:** Simple ~45%, Medium ~75% (risky), Complex 120% (impossible)
|
||||
</estimating_context>
|
||||
|
||||
<atomic_commits>
|
||||
|
||||
**What we're optimizing for:** Beautiful git history where each commit is:
|
||||
- Focused (2-3 related changes)
|
||||
- Complete (fully implemented, tested)
|
||||
- Documented (clear commit message)
|
||||
- Reviewable (small enough to understand)
|
||||
- Revertable (surgical rollback possible)
|
||||
|
||||
**Bad git history (large plans):**
|
||||
```
|
||||
feat(auth): Complete authentication system
|
||||
- Added 16 files
|
||||
- Modified 8 files
|
||||
- 1200 lines changed
|
||||
- Contains: models, API, UI, middleware, utilities
|
||||
```
|
||||
|
||||
Impossible to review, hard to understand, can't revert without losing everything.
|
||||
|
||||
**Good git history (atomic plans):**
|
||||
```
|
||||
feat(auth-01): Add User and Session database models
|
||||
- Added schema files
|
||||
- Added migration
|
||||
- 45 lines changed
|
||||
|
||||
feat(auth-02): Implement register and login API endpoints
|
||||
- Added /api/auth/register
|
||||
- Added /api/auth/login
|
||||
- Added JWT utilities
|
||||
- 120 lines changed
|
||||
|
||||
feat(auth-03): Add protected route middleware
|
||||
- Added middleware/auth.ts
|
||||
- Added tests
|
||||
- 60 lines changed
|
||||
|
||||
feat(auth-04): Build login and registration forms
|
||||
- Added LoginForm component
|
||||
- Added RegisterForm component
|
||||
- 90 lines changed
|
||||
```
|
||||
|
||||
Each commit tells a story. Each is reviewable. Each is revertable. This is craftsmanship.
|
||||
</atomic_commits>
|
||||
|
||||
<quality_assurance>
|
||||
|
||||
**The guarantee:** When you follow the 2-3 task rule with 50% context target:
|
||||
|
||||
1. **Consistency:** First task has same quality as last task
|
||||
2. **Thoroughness:** No "I'll complete X concisely" degradation
|
||||
3. **Documentation:** Full context budget for comments/tests
|
||||
4. **Error handling:** Space for proper validation and edge cases
|
||||
5. **Testing:** Room for comprehensive test coverage
|
||||
|
||||
**The cost:** More plans to manage.
|
||||
|
||||
**The benefit:** Consistent excellence. No rework. Clean history. Maintainable code.
|
||||
|
||||
**The trade-off is worth it.**
|
||||
</quality_assurance>
|
||||
|
||||
<summary>
|
||||
|
||||
**2-3 tasks, 50% context target:**
|
||||
- All tasks: Peak quality
|
||||
- Git: Atomic, surgical commits
|
||||
- Quality: Consistent excellence
|
||||
- Autonomous plans: Subagent execution (fresh context)
|
||||
|
||||
**The principle:** Aggressive atomicity. More plans, smaller scope, consistent quality.
|
||||
|
||||
@@ -5,38 +5,12 @@ Decimal phases enable urgent work insertion without renumbering:
|
||||
- Decimal phases (2.1, 2.2) = urgent insertions between integers
|
||||
|
||||
**Rules:**
|
||||
|
||||
- Decimals must be between consecutive integers (2.1 between 2 and 3)
|
||||
- Decimals between consecutive integers (2.1 between 2 and 3)
|
||||
- Filesystem sorting works automatically (2 < 2.1 < 2.2 < 3)
|
||||
- Execution order follows numeric sort
|
||||
- Directory format: `02.1-description/` (note the dot)
|
||||
- Plan format: `02.1-01-PLAN.md`
|
||||
- Directory format: `02.1-description/`, Plan format: `02.1-01-PLAN.md`
|
||||
|
||||
**Example:**
|
||||
|
||||
```
|
||||
Roadmap before insertion:
|
||||
- Phase 72: Analytics (complete)
|
||||
- Phase 73: Dashboard (planned)
|
||||
|
||||
User: "Need Sentry bugfix before Phase 73"
|
||||
|
||||
System creates Phase 72.1:
|
||||
- Phase 72: Analytics (complete)
|
||||
- Phase 72.1: Sentry Bugfix (INSERTED)
|
||||
- Phase 73: Dashboard (planned)
|
||||
|
||||
Execution order: 72 → 72.1 → 73
|
||||
```
|
||||
|
||||
**Validation:**
|
||||
When creating decimal phase X.Y:
|
||||
|
||||
1. Integer phase X must exist and be complete
|
||||
2. Integer phase X+1 must exist in roadmap
|
||||
3. Decimal X.Y must not already exist
|
||||
4. Y must be >= 1
|
||||
</decimal_phase_numbering>
|
||||
**Validation:** Integer X must exist and be complete, X+1 must exist, decimal X.Y must not exist, Y >= 1
|
||||
</decimal_phase_numbering>
|
||||
|
||||
<required_reading>
|
||||
**Read these files NOW:**
|
||||
@@ -45,140 +19,55 @@ When creating decimal phase X.Y:
|
||||
2. ~/.claude/get-shit-done/references/plan-format.md
|
||||
3. ~/.claude/get-shit-done/references/scope-estimation.md
|
||||
4. ~/.claude/get-shit-done/references/checkpoints.md
|
||||
5. Read `.planning/ROADMAP.md`
|
||||
6. Read `.planning/PROJECT.md`
|
||||
5. .planning/ROADMAP.md
|
||||
6. .planning/PROJECT.md
|
||||
|
||||
**Load domain expertise from ROADMAP:** 7. Parse ROADMAP.md's `## Domain Expertise` section for paths 8. Read each domain SKILL.md (these serve as indexes) 9. Determine phase type from ROADMAP (UI, database, API, shaders, etc.) 10. Check each SKILL.md's `<references_index>` section 11. Load ONLY references relevant to THIS phase type
|
||||
|
||||
**Example:** Planning a UI phase for an ISF shader macOS app:
|
||||
|
||||
- ROADMAP says: `expertise/isf-shaders`, `expertise/macos-apps`
|
||||
- Read both SKILL.md files
|
||||
- isf-shaders `<references_index>` says: "For UI phases: references/parameter-ui.md"
|
||||
- macos-apps `<references_index>` says: "For UI phases: references/swiftui-layout.md"
|
||||
- Load those two references, not everything
|
||||
</required_reading>
|
||||
**Load domain expertise from ROADMAP:**
|
||||
- Parse ROADMAP.md's `## Domain Expertise` section for paths
|
||||
- Read each domain SKILL.md (these serve as indexes)
|
||||
- Determine phase type and load ONLY references relevant to THIS phase type from each SKILL.md's `<references_index>`
|
||||
</required_reading>
|
||||
|
||||
<purpose>
|
||||
Create an executable phase prompt (PLAN.md). This is where we get specific:
|
||||
objective, context, tasks, verification, success criteria, and output specification.
|
||||
|
||||
**Key insight:** PLAN.md IS the prompt that Claude executes. Not a document that
|
||||
gets transformed into a prompt.
|
||||
Create an executable phase prompt (PLAN.md). PLAN.md IS the prompt that Claude executes - not a document that gets transformed.
|
||||
</purpose>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="load_project_state" priority="first">
|
||||
Before any planning, read project state:
|
||||
|
||||
```bash
|
||||
cat .planning/STATE.md 2>/dev/null
|
||||
```
|
||||
|
||||
**If file exists:** Parse and internalize:
|
||||
|
||||
Read `.planning/STATE.md` and parse:
|
||||
- Current position (which phase we're planning)
|
||||
- Accumulated decisions (constraints on this phase)
|
||||
- Deferred issues (candidates for inclusion in this phase)
|
||||
- Blockers/concerns (things this phase may need to address)
|
||||
- Brief alignment status (are we on track?)
|
||||
- Deferred issues (candidates for inclusion)
|
||||
- Blockers/concerns (things this phase may address)
|
||||
- Brief alignment status
|
||||
|
||||
**If file missing but .planning/ exists:**
|
||||
|
||||
```
|
||||
STATE.md missing but planning artifacts exist.
|
||||
Options:
|
||||
1. Reconstruct from existing artifacts
|
||||
2. Continue without project state (may lose accumulated context)
|
||||
```
|
||||
|
||||
This ensures planning has full project context.
|
||||
If STATE.md missing but .planning/ exists, offer to reconstruct or continue without.
|
||||
</step>
|
||||
|
||||
<step name="load_codebase_context">
|
||||
Check if codebase map exists:
|
||||
Check for `.planning/codebase/*.md` and load relevant documents based on phase type:
|
||||
|
||||
```bash
|
||||
ls .planning/codebase/*.md 2>/dev/null
|
||||
```
|
||||
| Phase Keywords | Load These |
|
||||
|----------------|------------|
|
||||
| UI, frontend, components | CONVENTIONS.md, STRUCTURE.md |
|
||||
| API, backend, endpoints | ARCHITECTURE.md, CONVENTIONS.md |
|
||||
| database, schema, models | ARCHITECTURE.md, STACK.md |
|
||||
| testing, tests | TESTING.md, CONVENTIONS.md |
|
||||
| integration, external API | INTEGRATIONS.md, STACK.md |
|
||||
| refactor, cleanup | CONCERNS.md, ARCHITECTURE.md |
|
||||
| setup, config | STACK.md, STRUCTURE.md |
|
||||
| (default) | STACK.md, ARCHITECTURE.md |
|
||||
|
||||
**If .planning/codebase/ exists:**
|
||||
|
||||
Determine which codebase documents are relevant based on phase goal:
|
||||
|
||||
| Phase Keywords | Load These Documents |
|
||||
|----------------|---------------------|
|
||||
| UI, frontend, components, layout | CONVENTIONS.md, STRUCTURE.md |
|
||||
| API, backend, endpoints, routes | ARCHITECTURE.md, CONVENTIONS.md |
|
||||
| database, schema, models, migration | ARCHITECTURE.md, STACK.md |
|
||||
| testing, tests, coverage | TESTING.md, CONVENTIONS.md |
|
||||
| integration, external, API, service | INTEGRATIONS.md, STACK.md |
|
||||
| refactor, cleanup, debt | CONCERNS.md, ARCHITECTURE.md |
|
||||
| setup, config, infrastructure | STACK.md, STRUCTURE.md |
|
||||
| (default - load minimal set) | STACK.md, ARCHITECTURE.md |
|
||||
|
||||
Read the relevant documents and summarize key constraints for this phase:
|
||||
- From STACK.md: Technologies that must be used
|
||||
- From ARCHITECTURE.md: Patterns that must be followed
|
||||
- From CONVENTIONS.md: Code style requirements
|
||||
- From CONCERNS.md: Issues to avoid or address
|
||||
|
||||
**Add to planning context:**
|
||||
Track codebase constraints for inclusion in PLAN.md context section:
|
||||
- Which documents loaded
|
||||
- Key constraints extracted
|
||||
- Patterns to follow
|
||||
|
||||
**If .planning/codebase/ doesn't exist:**
|
||||
Skip this step - no codebase map available.
|
||||
Track extracted constraints for PLAN.md context section.
|
||||
</step>
|
||||
|
||||
<step name="identify_phase">
|
||||
Check roadmap for phases:
|
||||
```bash
|
||||
cat .planning/ROADMAP.md
|
||||
ls .planning/phases/
|
||||
```
|
||||
Check roadmap and existing phases. If multiple phases available, ask which one to plan.
|
||||
|
||||
If multiple phases available, ask which one to plan.
|
||||
If obvious (first incomplete phase), proceed.
|
||||
**Phase number parsing:** Regex `^(\d+)(?:\.(\d+))?$` - Group 1: integer, Group 2: decimal (optional)
|
||||
|
||||
**Phase number parsing:**
|
||||
|
||||
When user provides phase number, parse using regex: `^(\d+)(?:\.(\d+))?$`
|
||||
|
||||
- Group 1: Integer part (required) - e.g., "2" from "2" or "2.1"
|
||||
- Group 2: Decimal part (optional) - e.g., "1" from "2.1"
|
||||
|
||||
**If decimal phase (e.g., 72.1):**
|
||||
|
||||
Validate insertion:
|
||||
|
||||
1. Check integer phase X (72) exists in roadmap: `grep "Phase 72:" ROADMAP.md`
|
||||
2. Check integer phase X (72) is complete: Look for "Complete" status
|
||||
3. Check integer phase X+1 (73) exists in roadmap: `grep "Phase 73:" ROADMAP.md`
|
||||
4. Check decimal X.Y (72.1) doesn't already exist: `ls .planning/phases/ | grep "^72\.1-"`
|
||||
5. Decimal part Y must be >= 1
|
||||
|
||||
If validation fails, explain issue and suggest correction.
|
||||
|
||||
**Directory naming:**
|
||||
|
||||
```bash
|
||||
# Integer phase: 01-foundation
|
||||
# Decimal phase: 01.1-hotfix
|
||||
|
||||
if decimal:
|
||||
DIR_NAME="${PHASE_INT}.${PHASE_DEC}-${SLUG}"
|
||||
else:
|
||||
DIR_NAME="${PHASE_INT}-${SLUG}"
|
||||
fi
|
||||
```
|
||||
|
||||
**Roadmap marking:**
|
||||
|
||||
When creating decimal phases, mark them as "(INSERTED)" in roadmap entries.
|
||||
**If decimal phase:** Validate integer X exists and is complete, X+1 exists in roadmap, decimal X.Y doesn't exist, Y >= 1.
|
||||
|
||||
Read any existing PLAN.md or DISCOVERY.md in the phase directory.
|
||||
</step>
|
||||
@@ -186,294 +75,74 @@ Read any existing PLAN.md or DISCOVERY.md in the phase directory.
|
||||
<step name="mandatory_discovery">
|
||||
**Discovery is MANDATORY unless you can prove current context exists.**
|
||||
|
||||
Claude's training data is 6-18 months stale. Treat pre-existing knowledge as hypothesis, not fact.
|
||||
<discovery_decision>
|
||||
**Level 0 - Skip** (pure internal work, existing patterns only)
|
||||
- ALL work follows established codebase patterns (grep confirms)
|
||||
- No new external dependencies
|
||||
- Pure internal refactoring or feature extension
|
||||
- Examples: Add delete button, add field to model, create CRUD endpoint
|
||||
|
||||
<discovery_decision_tree>
|
||||
|
||||
````
|
||||
Starting discovery for Phase [X]...
|
||||
↓
|
||||
CHECK ROADMAP FLAG FIRST
|
||||
─────────────────────────────────────
|
||||
```bash
|
||||
# Check if roadmap flagged this phase for research
|
||||
grep -A2 "Phase [X]:" .planning/ROADMAP.md | grep "Research:"
|
||||
```
|
||||
|
||||
→ If `Research: Likely` → Minimum depth is Level 1 (don't skip to Level 0)
|
||||
→ If `Research: Unlikely` → Level 0 check still runs (might escalate)
|
||||
→ Flag is a hint, not a mandate - actual depth determined below
|
||||
↓
|
||||
LEVEL 0: Pattern Check (30 seconds)
|
||||
─────────────────────────────────────
|
||||
**Skip this check if roadmap flagged Research: Likely**
|
||||
|
||||
Is this pure internal work using ONLY existing codebase patterns?
|
||||
|
||||
Check with:
|
||||
|
||||
```bash
|
||||
# Look for existing patterns in codebase
|
||||
grep -r "libraryName" src/ 2>/dev/null | head -5
|
||||
ls src/components/ 2>/dev/null # existing UI patterns
|
||||
cat package.json 2>/dev/null | grep -A5 '"dependencies"'
|
||||
```
|
||||
|
||||
→ If ALL work follows established codebase patterns: SKIP discovery, proceed to planning
|
||||
→ If ANY external dependency, new library, or API integration: Continue to Level 1+
|
||||
↓
|
||||
Does fresh DISCOVERY.md exist?
|
||||
─────────────────────────────────────
|
||||
|
||||
```bash
|
||||
ls .planning/phases/XX-name/DISCOVERY.md 2>/dev/null
|
||||
```
|
||||
|
||||
If exists, check freshness:
|
||||
|
||||
- General libraries/frameworks: Valid for 30 days
|
||||
- Fast-moving APIs (Stripe, OpenAI, etc.): Valid for 7 days
|
||||
- Check file date vs today
|
||||
|
||||
→ If fresh DISCOVERY.md exists covering this phase's topics: SKIP discovery, use existing
|
||||
→ If missing or stale: Continue to determine depth
|
||||
↓
|
||||
Determine Discovery Depth
|
||||
─────────────────────────────────────
|
||||
Assess the phase requirements:
|
||||
|
||||
**LEVEL 1 - Quick Verification (2-5 min):**
|
||||
Use when:
|
||||
|
||||
- Single known library, just confirming syntax/version
|
||||
**Level 1 - Quick Verification** (2-5 min)
|
||||
- Single known library, confirming syntax/version
|
||||
- Low-risk decision (easily changed later)
|
||||
- "Is X still the right choice?"
|
||||
|
||||
Action:
|
||||
|
||||
1. Context7: mcp**context7**resolve-library-id → mcp**context7**get-library-docs
|
||||
2. Verify current version/API matches expectations
|
||||
3. No DISCOVERY.md needed - proceed with confirmed knowledge
|
||||
|
||||
**LEVEL 2 - Standard Research (15-30 min):**
|
||||
Use when:
|
||||
- Action: Context7 resolve-library-id + query-docs, no DISCOVERY.md needed
|
||||
|
||||
**Level 2 - Standard Research** (15-30 min)
|
||||
- Choosing between 2-3 options
|
||||
- New external integration (API, service)
|
||||
- Medium-risk decision
|
||||
- Action: Route to workflows/discovery-phase.md depth=standard, produces DISCOVERY.md
|
||||
|
||||
Action:
|
||||
|
||||
1. Route to workflows/discovery-phase.md with depth=standard
|
||||
2. Produces DISCOVERY.md with recommendation
|
||||
3. Return here after DISCOVERY.md created
|
||||
|
||||
**LEVEL 3 - Deep Dive (1+ hour):**
|
||||
Use when:
|
||||
|
||||
**Level 3 - Deep Dive** (1+ hour)
|
||||
- Architectural decision with long-term impact
|
||||
- Novel problem without clear patterns
|
||||
- High-risk, hard to change later
|
||||
- Multiple interacting systems
|
||||
- Action: Route to workflows/discovery-phase.md depth=deep, full DISCOVERY.md
|
||||
|
||||
Action:
|
||||
**Depth indicators:**
|
||||
- Level 2+: New library not in package.json, external API, "choose/select/evaluate" in description, roadmap marked Research: Yes
|
||||
- Level 3: "architecture/design/system", multiple external services, data modeling, auth design, real-time/distributed
|
||||
</discovery_decision>
|
||||
|
||||
1. Route to workflows/discovery-phase.md with depth=deep
|
||||
2. Full discovery with cross-verification
|
||||
3. DISCOVERY.md with detailed rationale and validation checkpoints
|
||||
4. Return here after DISCOVERY.md created
|
||||
If roadmap flagged `Research: Likely`, Level 0 (skip) is not available.
|
||||
|
||||
**NOTE:** For niche/complex domains (3D, games, audio, shaders, ML), consider using `/gsd:research-phase` BEFORE plan-phase. This produces comprehensive RESEARCH.md with ecosystem knowledge that goes beyond "which library" to "how do experts build this."
|
||||
|
||||
```
|
||||
</discovery_decision_tree>
|
||||
|
||||
<depth_indicators>
|
||||
**Signals requiring LEVEL 2+:**
|
||||
- Phase involves new library not in package.json
|
||||
- Phase involves external API integration
|
||||
- Phase description includes "choose", "select", "evaluate"
|
||||
- Roadmap marked this phase with `Research: Yes`
|
||||
- Technology mentioned that Claude hasn't used in THIS codebase
|
||||
|
||||
**Signals requiring LEVEL 3:**
|
||||
- Words like "architecture", "design", "system"
|
||||
- Integration between multiple external services
|
||||
- Data modeling decisions
|
||||
- Authentication/authorization design
|
||||
- Real-time, sync, or distributed systems
|
||||
</depth_indicators>
|
||||
|
||||
<skip_conditions>
|
||||
**Discovery can be skipped (Level 0) ONLY when ALL true:**
|
||||
□ Pattern already exists in codebase (grep confirms)
|
||||
□ No new external dependencies
|
||||
□ Fresh DISCOVERY.md exists (if external deps involved)
|
||||
□ Pure internal refactoring or feature extension
|
||||
□ Using established project conventions only
|
||||
|
||||
**Examples that skip discovery:**
|
||||
- "Add delete button" → existing button patterns in codebase
|
||||
- "Add field to model" → Prisma/schema patterns established
|
||||
- "Create CRUD endpoint" → existing API patterns to follow
|
||||
|
||||
**Examples that REQUIRE discovery:**
|
||||
- "Add authentication" → Level 2-3 (new system, choices to make)
|
||||
- "Integrate Stripe" → Level 2 (external API)
|
||||
- "Add email service" → Level 2 (compare options)
|
||||
- "Design data sync" → Level 3 (architectural)
|
||||
</skip_conditions>
|
||||
|
||||
Present discovery decision:
|
||||
```
|
||||
|
||||
Phase [X]: [Name]
|
||||
|
||||
Discovery assessment:
|
||||
|
||||
- Roadmap flag: [Likely / Unlikely] ([reason from roadmap])
|
||||
- Roadmap topics: [topics if flagged, or N/A]
|
||||
- New external dependencies: [yes/no - list them]
|
||||
- Existing DISCOVERY.md: [yes (date) / no]
|
||||
- Codebase patterns exist: [yes/no]
|
||||
|
||||
Discovery depth: [Level 0 (skip) / Level 1 (verify) / Level 2 (standard) / Level 3 (deep)]
|
||||
Reason: [one line explanation]
|
||||
|
||||
[If Level 1: Proceeding with quick verification...]
|
||||
[If Level 2-3: Routing to research workflow...]
|
||||
[If Level 0: Skipping discovery, proceeding to planning...]
|
||||
|
||||
````
|
||||
|
||||
**Note:** If roadmap flagged `Research: Likely`, Level 0 (skip) is not available.
|
||||
The roadmap flag lowers the bar for triggering research but doesn't guarantee depth.
|
||||
For niche domains (3D, games, audio, shaders, ML), suggest `/gsd:research-phase` before plan-phase.
|
||||
</step>
|
||||
|
||||
<step name="read_project_history">
|
||||
Before planning, absorb accumulated project wisdom. This is the **context injection** that ensures each phase benefits from all prior phases.
|
||||
**From STATE.md:** Decisions → constrain approach. Deferred issues → candidates. Blockers → may need to address.
|
||||
|
||||
**1. From STATE.md (already loaded):**
|
||||
**From prior summaries:** Scan `.planning/phases/*/*-SUMMARY.md` for decisions constraining this phase, issues flagged for "later", warnings in "Next Phase Readiness", patterns to maintain.
|
||||
|
||||
- Decisions table → These CONSTRAIN this phase's approach
|
||||
- Deferred issues → Candidates for inclusion in this phase
|
||||
- Blockers/concerns → Things this phase may need to address
|
||||
**From ISSUES.md:** Assess each open issue - relevant to this phase? Waiting long enough? Natural to address now? Blocking something?
|
||||
|
||||
**2. Read previous phase summaries:**
|
||||
**Answer before proceeding:**
|
||||
- Q1: What decisions from previous phases constrain this phase?
|
||||
- Q2: Are there deferred issues that should become tasks?
|
||||
- Q3: Are there concerns from "Next Phase Readiness" that apply?
|
||||
- Q4: Given all context, does the roadmap's description still make sense?
|
||||
|
||||
```bash
|
||||
# List all summaries from prior phases
|
||||
ls .planning/phases/*/*-SUMMARY.md 2>/dev/null | sort
|
||||
```
|
||||
|
||||
Don't load ALL summaries into context—scan them looking for:
|
||||
|
||||
- Decisions that constrain this phase's approach
|
||||
- Issues flagged for "later" where "later" is now
|
||||
- Warnings in "Next Phase Readiness" that apply
|
||||
- Patterns established that should be maintained
|
||||
|
||||
**3. Read ISSUES.md:**
|
||||
|
||||
```bash
|
||||
cat .planning/ISSUES.md 2>/dev/null
|
||||
```
|
||||
|
||||
For each open issue, assess:
|
||||
|
||||
- Is this relevant to the phase being planned?
|
||||
- Has it been waiting long enough to address?
|
||||
- Would addressing it now be natural (same files/subsystem)?
|
||||
- Is it blocking something this phase needs?
|
||||
|
||||
**4. Synthesize into planning context:**
|
||||
|
||||
Before proceeding to task breakdown, answer:
|
||||
|
||||
**Q1: What decisions from previous phases constrain this phase?**
|
||||
→ These become explicit notes in task `<action>` sections
|
||||
Example: "Use jose (NOT jsonwebtoken - see Phase 1 decision)"
|
||||
|
||||
**Q2: Are there deferred issues that should become tasks?**
|
||||
→ These get added to the task list, marked "Addressing ISS-XXX"
|
||||
Example: "Task 3: Add rate limiting (ISS-001 from Phase 2)"
|
||||
|
||||
**Q3: Are there concerns from "Next Phase Readiness" that apply?**
|
||||
→ These inform verification criteria or become explicit tasks
|
||||
Example: "Load test auth endpoints (Phase 2 concern)"
|
||||
|
||||
**Q4: Given all context, does the roadmap's description still make sense?**
|
||||
→ If not, flag: "Phase as described may need adjustment because [X]"
|
||||
|
||||
**5. Document what will inform the plan:**
|
||||
|
||||
Track for inclusion in PLAN.md `<context>` section:
|
||||
|
||||
- Which prior summaries are relevant (will be @referenced)
|
||||
- Which decisions apply (brief notes)
|
||||
- Which issues are being addressed (ISS-XXX numbers)
|
||||
- Which concerns are being verified
|
||||
</step>
|
||||
Track for PLAN.md context section: relevant summaries, applicable decisions, issues being addressed, concerns being verified.
|
||||
</step>
|
||||
|
||||
<step name="gather_phase_context">
|
||||
For this specific phase, understand:
|
||||
- What's the phase goal? (from roadmap)
|
||||
- What exists already? (scan codebase if mid-project)
|
||||
- What dependencies are met? (previous phases complete?)
|
||||
- Any ecosystem research? (RESEARCH.md from /gsd:research-phase)
|
||||
- Any discovery findings? (DISCOVERY.md from mandatory discovery)
|
||||
- Any phase context? ({phase}-CONTEXT.md from /gsd:discuss-phase)
|
||||
Understand:
|
||||
- Phase goal (from roadmap)
|
||||
- What exists already (scan codebase if mid-project)
|
||||
- Dependencies met (previous phases complete?)
|
||||
- Any {phase}-RESEARCH.md (from /gsd:research-phase)
|
||||
- Any DISCOVERY.md (from mandatory discovery)
|
||||
- Any {phase}-CONTEXT.md (from /gsd:discuss-phase)
|
||||
|
||||
```bash
|
||||
# If mid-project, understand current state
|
||||
ls -la src/ 2>/dev/null
|
||||
cat package.json 2>/dev/null | head -20
|
||||
**If RESEARCH.md exists:** Use standard_stack (these libraries), architecture_patterns (follow in task structure), dont_hand_roll (NEVER custom solutions for listed problems), common_pitfalls (inform verification), code_examples (reference in actions).
|
||||
|
||||
# Check for comprehensive ecosystem research (created by /gsd:research-phase)
|
||||
cat .planning/phases/XX-name/${PHASE}-RESEARCH.md 2>/dev/null
|
||||
|
||||
# Check for phase-specific context (created by /gsd:discuss-phase)
|
||||
cat .planning/phases/XX-name/${PHASE}-CONTEXT.md 2>/dev/null
|
||||
```
|
||||
|
||||
**If {phase}-RESEARCH.md exists:**
|
||||
This file contains comprehensive ecosystem research for niche/complex domains. It captures:
|
||||
- Standard stack (libraries, versions, why they're standard)
|
||||
- Architecture patterns (how experts structure this type of project)
|
||||
- Don't hand-roll list (problems with existing solutions - use libraries instead)
|
||||
- Common pitfalls (mistakes to avoid)
|
||||
- Code examples (verified patterns from authoritative sources)
|
||||
|
||||
**You MUST use this research to inform your planning:**
|
||||
|
||||
- `<standard_stack>` → use these libraries, don't pick alternatives without reason
|
||||
- `<architecture_patterns>` → follow these patterns in task structure
|
||||
- `<dont_hand_roll>` → NEVER create custom solutions for listed problems
|
||||
- `<common_pitfalls>` → inform verification criteria, add warnings to task actions
|
||||
- `<code_examples>` → reference in task actions when applicable
|
||||
|
||||
**If {phase}-CONTEXT.md exists:**
|
||||
This file contains the user's vision gathered through pre-planning discussion. It captures how they imagine this phase working, what's essential, and what's out of scope.
|
||||
|
||||
**You MUST use this context to inform your planning:**
|
||||
|
||||
- `<vision>` → how the user imagines this working (honor their intent)
|
||||
- `<essential>` → what must be nailed in this phase (prioritize these)
|
||||
- `<boundaries>` → what's explicitly out of scope (don't add these)
|
||||
- `<specifics>` → particular look/feel/behavior mentioned (incorporate these)
|
||||
- `<notes>` → additional context that informs approach
|
||||
|
||||
**If neither RESEARCH.md nor CONTEXT.md exist:**
|
||||
For niche domains (3D, games, audio, shaders, etc.), suggest `/gsd:research-phase {phase}` first.
|
||||
For simpler domains, suggest `/gsd:discuss-phase {phase}` or proceed with roadmap description only.
|
||||
**If CONTEXT.md exists:** Honor vision, prioritize essential, respect boundaries, incorporate specifics.
|
||||
|
||||
**If neither exist:** Suggest /gsd:research-phase for niche domains, /gsd:discuss-phase for simpler domains, or proceed with roadmap only.
|
||||
</step>
|
||||
|
||||
<step name="break_into_tasks">
|
||||
Decompose the phase into tasks.
|
||||
|
||||
Each task must have:
|
||||
|
||||
Decompose phase into tasks. Each task needs:
|
||||
- **Type**: auto, checkpoint:human-verify, checkpoint:decision (human-action rarely needed)
|
||||
- **Task name**: Clear, action-oriented
|
||||
- **Files**: Which files created/modified (for auto tasks)
|
||||
@@ -481,168 +150,62 @@ Each task must have:
|
||||
- **Verify**: How to prove it worked
|
||||
- **Done**: Acceptance criteria
|
||||
|
||||
**Assess TDD fit for each task:**
|
||||
**TDD fit:** Can you write `expect(fn(input)).toBe(output)` before writing `fn`? Yes (business logic, APIs, validation) → test-first. No (UI layout, config, glue code) → standard implementation.
|
||||
|
||||
TDD produces better design and catches bugs early. Use it when you can define expected behavior upfront.
|
||||
**Checkpoints:** Visual/functional verification → checkpoint:human-verify. Implementation choices → checkpoint:decision. Manual action (email, 2FA) → checkpoint:human-action (rare).
|
||||
|
||||
For each task, ask: Can I write `expect(fn(input)).toBe(output)` before writing `fn`?
|
||||
**Critical:** If external resource has CLI/API (Vercel, Stripe, etc.), use type="auto" to automate. Only checkpoint for verification AFTER automation.
|
||||
|
||||
→ **Yes** (business logic, APIs, transformations, validation, state machines):
|
||||
Structure test-first. Task action: "Implement X with TDD—write failing test, then implement to pass."
|
||||
|
||||
→ **No** (UI layout, config, glue code, exploration):
|
||||
Standard implementation. Add tests after if coverage needed.
|
||||
|
||||
**Identify checkpoints:**
|
||||
|
||||
- Claude automated work needing visual/functional verification? → checkpoint:human-verify
|
||||
- Implementation choices to make? → checkpoint:decision
|
||||
- Truly unavoidable manual action (email link, 2FA)? → checkpoint:human-action (rare)
|
||||
|
||||
**Critical:** If external resource has CLI/API (Vercel, Stripe, Upstash, GitHub, etc.), use type="auto" to automate it. Only checkpoint for verification AFTER automation.
|
||||
|
||||
See ~/.claude/get-shit-done/references/checkpoints.md for checkpoint structure and automation guidance.
|
||||
See ~/.claude/get-shit-done/references/checkpoints.md for checkpoint structure.
|
||||
</step>
|
||||
|
||||
<step name="estimate_scope">
|
||||
After breaking into tasks, assess scope against the **quality degradation curve**.
|
||||
After tasks, assess against quality degradation curve.
|
||||
|
||||
**ALWAYS split if:**
|
||||
**ALWAYS split if:** >3 tasks, multiple subsystems, >5 files in any task, complex domains (auth, payments).
|
||||
|
||||
- > 3 tasks total
|
||||
- Multiple subsystems (DB + API + UI = separate plans)
|
||||
- > 5 files modified in any single task
|
||||
- Complex domains (auth, payments, data modeling)
|
||||
**If scope appropriate (2-3 tasks, single subsystem, <5 files/task):** Proceed to confirm_breakdown.
|
||||
|
||||
**Aggressive atomicity principle:** Better to have 10 small, high-quality plans than 3 large, degraded plans.
|
||||
**If large (>3 tasks):** Split by subsystem, dependency, complexity, or autonomous vs interactive.
|
||||
|
||||
**If scope is appropriate (2-3 tasks, single subsystem, <5 files per task):**
|
||||
Proceed to confirm_breakdown for a single plan.
|
||||
**Each plan must be:** 2-3 tasks max, ~50% context target, independently committable.
|
||||
|
||||
**If scope is large (>3 tasks):**
|
||||
Split into multiple plans by:
|
||||
**Autonomous optimization:** No checkpoints → subagent (fresh context). Has checkpoints → main context. Group autonomous work together.
|
||||
|
||||
- Subsystem (01-01: Database, 01-02: API, 01-03: UI, 01-04: Frontend)
|
||||
- Dependency (01-01: Setup, 01-02: Core, 01-03: Features, 01-04: Testing)
|
||||
- Complexity (01-01: Layout, 01-02: Data fetch, 01-03: Visualization)
|
||||
- Autonomous vs Interactive (group auto tasks for subagent execution)
|
||||
|
||||
**Each plan must be:**
|
||||
|
||||
- 2-3 tasks maximum
|
||||
- ~50% context target (not 80%)
|
||||
- Independently committable
|
||||
|
||||
**Autonomous plan optimization:**
|
||||
|
||||
- Plans with NO checkpoints → will execute via subagent (fresh context)
|
||||
- Plans with checkpoints → execute in main context (user interaction required)
|
||||
- Try to group autonomous work together for maximum fresh contexts
|
||||
|
||||
See ~/.claude/get-shit-done/references/scope-estimation.md for complete splitting guidance and quality degradation analysis.
|
||||
See ~/.claude/get-shit-done/references/scope-estimation.md for complete guidance.
|
||||
</step>
|
||||
|
||||
<step name="confirm_breakdown">
|
||||
<config-check>
|
||||
```bash
|
||||
cat .planning/config.json 2>/dev/null
|
||||
```
|
||||
</config-check>
|
||||
|
||||
<if mode="yolo">
|
||||
```
|
||||
⚡ Auto-approved: Phase [X] breakdown ([N] tasks, [M] plan(s))
|
||||
|
||||
[Brief breakdown summary - task names and types only]
|
||||
|
||||
Proceeding to plan creation...
|
||||
```
|
||||
|
||||
Skip directly to write_phase_prompt step.
|
||||
Auto-approve and proceed to write_phase_prompt.
|
||||
</if>
|
||||
|
||||
<if mode="interactive" OR="custom with gates.confirm_breakdown true">
|
||||
Present the breakdown inline and wait for confirmation:
|
||||
|
||||
**If single plan (2-3 tasks):**
|
||||
<if mode="interactive">
|
||||
Present breakdown inline:
|
||||
|
||||
```
|
||||
Here's the proposed breakdown for Phase [X]:
|
||||
Phase [X] breakdown:
|
||||
|
||||
### Tasks (single plan: {phase}-01-PLAN.md)
|
||||
1. [Task name] - [brief description] [type: auto/checkpoint]
|
||||
2. [Task name] - [brief description] [type: auto/checkpoint]
|
||||
[3. [Task name] - [brief description] [type: auto/checkpoint]] (optional 3rd task if small)
|
||||
### Tasks ({phase}-01-PLAN.md)
|
||||
1. [Task] - [brief] [type]
|
||||
2. [Task] - [brief] [type]
|
||||
|
||||
Autonomous: [yes/no] (no checkpoints = subagent execution with fresh context)
|
||||
Autonomous: [yes/no]
|
||||
|
||||
Does this breakdown look right? (yes / adjust / start over)
|
||||
Does this look right? (yes / adjust / start over)
|
||||
```
|
||||
|
||||
**If multiple plans (>3 tasks or multiple subsystems):**
|
||||
For multiple plans, show each plan with its tasks.
|
||||
|
||||
```
|
||||
Here's the proposed breakdown for Phase [X]:
|
||||
|
||||
This phase requires [N] plans to maintain quality:
|
||||
|
||||
### Plan 1: {phase}-01-PLAN.md - [Subsystem/Component Name]
|
||||
1. [Task name] - [brief description] [type]
|
||||
2. [Task name] - [brief description] [type]
|
||||
3. [Task name] - [brief description] [type]
|
||||
|
||||
### Plan 2: {phase}-02-PLAN.md - [Subsystem/Component Name]
|
||||
1. [Task name] - [brief description] [type]
|
||||
2. [Task name] - [brief description] [type]
|
||||
|
||||
[Additional plans as needed...]
|
||||
|
||||
Each plan is independently executable and scoped to ~50% context.
|
||||
|
||||
Does this breakdown look right? (yes / adjust / start over)
|
||||
```
|
||||
|
||||
Wait for confirmation before proceeding.
|
||||
|
||||
If "adjust": Ask what to change, revise, present again.
|
||||
If "start over": Return to gather_phase_context step.
|
||||
Wait for confirmation. If "adjust": revise. If "start over": return to gather_phase_context.
|
||||
</if>
|
||||
</step>
|
||||
|
||||
<step name="approach_ambiguity">
|
||||
If multiple valid approaches exist for any task:
|
||||
|
||||
Use AskUserQuestion:
|
||||
|
||||
- header: "Approach"
|
||||
- question: "For [task], there are multiple valid approaches:"
|
||||
- options:
|
||||
- "[Approach A]" - [tradeoff description]
|
||||
- "[Approach B]" - [tradeoff description]
|
||||
- "Decide for me" - Use your best judgment
|
||||
|
||||
Only ask if genuinely ambiguous. Don't ask obvious choices.
|
||||
</step>
|
||||
|
||||
<step name="decision_gate">
|
||||
<if mode="yolo">
|
||||
```
|
||||
⚡ Auto-approved: Create phase prompt for Phase [X]
|
||||
```
|
||||
|
||||
Skip directly to write_phase_prompt step.
|
||||
</if>
|
||||
|
||||
<if mode="interactive" OR="custom with gates.confirm_plan true">
|
||||
Use AskUserQuestion:
|
||||
|
||||
- header: "Ready"
|
||||
- question: "Ready to create the phase prompt, or would you like me to ask more questions?"
|
||||
- options:
|
||||
- "Create phase prompt" - I have enough context
|
||||
- "Ask more questions" - There are details to clarify
|
||||
- "Let me add context" - I want to provide more information
|
||||
|
||||
<if mode="yolo">Auto-approve and proceed.</if>
|
||||
<if mode="interactive">
|
||||
Ask: "Ready to create the phase prompt, or ask more questions?"
|
||||
Options: Create phase prompt / Ask more questions / Let me add context
|
||||
Loop until "Create phase prompt" selected.
|
||||
</if>
|
||||
</step>
|
||||
@@ -650,165 +213,41 @@ Loop until "Create phase prompt" selected.
|
||||
<step name="write_phase_prompt">
|
||||
Use template from `~/.claude/get-shit-done/templates/phase-prompt.md`.
|
||||
|
||||
**If single plan:**
|
||||
Write to `.planning/phases/XX-name/{phase}-01-PLAN.md`
|
||||
**Single plan:** Write to `.planning/phases/XX-name/{phase}-01-PLAN.md`
|
||||
|
||||
**If multiple plans:**
|
||||
Write multiple files:
|
||||
**Multiple plans:** Write separate files ({phase}-01-PLAN.md, {phase}-02-PLAN.md, etc.)
|
||||
|
||||
- `.planning/phases/XX-name/{phase}-01-PLAN.md`
|
||||
- `.planning/phases/XX-name/{phase}-02-PLAN.md`
|
||||
- `.planning/phases/XX-name/{phase}-03-PLAN.md`
|
||||
Each plan follows template structure with:
|
||||
- Frontmatter (phase, plan, type, domain)
|
||||
- Objective (plan-specific goal, purpose, output)
|
||||
- Execution context (execute-phase.md, summary template, checkpoints.md if needed)
|
||||
- Context (@references to PROJECT, ROADMAP, STATE, codebase docs, RESEARCH/DISCOVERY/CONTEXT if exist, prior summaries, source files, prior decisions, deferred issues, concerns)
|
||||
- Tasks (XML format with types)
|
||||
- Verification, Success criteria, Output specification
|
||||
|
||||
Each file follows the template structure:
|
||||
|
||||
```markdown
|
||||
---
|
||||
phase: XX-name
|
||||
plan: { plan-number }
|
||||
type: execute
|
||||
domain: [if domain expertise loaded]
|
||||
---
|
||||
|
||||
<objective>
|
||||
[Plan-specific goal - what this plan accomplishes]
|
||||
|
||||
Purpose: [Why this plan matters for the phase]
|
||||
Output: [What artifacts will be created by this plan]
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
./execute-phase.md
|
||||
~/.claude/get-shit-done/templates/summary.md
|
||||
[If plan has ANY checkpoint tasks (type="checkpoint:*"), add:]
|
||||
~/.claude/get-shit-done/references/checkpoints.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/STATE.md
|
||||
|
||||
[If codebase map exists (from /gsd:map-codebase):]
|
||||
@.planning/codebase/STACK.md
|
||||
@.planning/codebase/ARCHITECTURE.md
|
||||
[Add other relevant docs based on phase type - see load_codebase_context step]
|
||||
|
||||
**Codebase constraints:**
|
||||
- [Extracted constraints from codebase documents]
|
||||
- [Technologies that must be used]
|
||||
- [Patterns that must be followed]
|
||||
|
||||
[If comprehensive ecosystem research exists (from /gsd:research-phase):]
|
||||
@.planning/phases/XX-name/{phase}-RESEARCH.md
|
||||
|
||||
[If discovery done (from mandatory discovery):]
|
||||
@.planning/phases/XX-name/DISCOVERY.md
|
||||
|
||||
[If phase context exists (from /gsd:discuss-phase):]
|
||||
@.planning/phases/XX-name/{phase}-CONTEXT.md
|
||||
|
||||
[If continuing from previous plan in same phase:]
|
||||
@.planning/phases/XX-name/{phase}-{prev}-SUMMARY.md
|
||||
|
||||
[Prior phase summaries relevant to this work (from read_project_history):]
|
||||
@.planning/phases/01-foundation/01-02-SUMMARY.md # If contains relevant decisions
|
||||
@.planning/phases/02-auth/02-01-SUMMARY.md # If contains relevant patterns
|
||||
|
||||
[Document what prior context informed this plan:]
|
||||
**Prior decisions affecting this phase:**
|
||||
|
||||
- [Decision from Phase X that constrains approach]
|
||||
- [Decision from Phase Y that establishes pattern]
|
||||
|
||||
**Deferred issues being addressed:**
|
||||
|
||||
- ISS-XXX: [description] (from Phase Z)
|
||||
|
||||
**Concerns being verified:**
|
||||
|
||||
- [Concern from Phase W's "Next Phase Readiness"]
|
||||
|
||||
[Relevant source files:]
|
||||
@src/path/to/relevant.ts
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
[Tasks in XML format with type attribute]
|
||||
[Mix of type="auto" and type="checkpoint:*" as needed]
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
[Overall plan verification checks]
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
[Measurable completion criteria for this plan]
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
|
||||
[Include summary structure from template]
|
||||
</output>
|
||||
```
|
||||
|
||||
**For multi-plan phases:**
|
||||
|
||||
- Each plan has focused scope (3-6 tasks)
|
||||
- Plans reference previous plan summaries in context
|
||||
- Last plan's success criteria includes "Phase X complete"
|
||||
</step>
|
||||
For multi-plan phases: each plan has focused scope, references previous plan summaries, last plan's success criteria includes "Phase X complete".
|
||||
</step>
|
||||
|
||||
<step name="offer_next">
|
||||
**If single plan:**
|
||||
```
|
||||
Phase plan created: .planning/phases/XX-name/{phase}-01-PLAN.md
|
||||
[X] tasks defined.
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
## Next Up
|
||||
|
||||
**{phase}-01: [Plan Name]** — [objective summary]
|
||||
**{phase}-01: [Plan Name]** - [objective summary]
|
||||
|
||||
`/gsd:execute-plan .planning/phases/XX-name/{phase}-01-PLAN.md`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
<sub>`/clear` first - fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- Review/adjust tasks before executing
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
**If multiple plans:**
|
||||
```
|
||||
|
||||
Phase plans created:
|
||||
|
||||
- {phase}-01-PLAN.md ([X] tasks) - [Subsystem name]
|
||||
- {phase}-02-PLAN.md ([X] tasks) - [Subsystem name]
|
||||
- {phase}-03-PLAN.md ([X] tasks) - [Subsystem name]
|
||||
|
||||
Total: [X] tasks across [Y] focused plans.
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**{phase}-01: [Plan Name]** — [objective summary]
|
||||
|
||||
`/gsd:execute-plan .planning/phases/XX-name/{phase}-01-PLAN.md`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- Review/adjust tasks before executing
|
||||
- View all plans: `ls .planning/phases/XX-name/*-PLAN.md`
|
||||
[If multiple plans: - View all plans: `ls .planning/phases/XX-name/*-PLAN.md`]
|
||||
|
||||
---
|
||||
```
|
||||
@@ -817,48 +256,35 @@ Total: [X] tasks across [Y] focused plans.
|
||||
</process>
|
||||
|
||||
<task_quality>
|
||||
Good tasks:
|
||||
**Good tasks:** Specific files, actions, verification
|
||||
- "Add User model to Prisma schema with email, passwordHash, createdAt"
|
||||
- "Create POST /api/auth/login endpoint with bcrypt validation"
|
||||
- "Add protected route middleware checking JWT in cookies"
|
||||
|
||||
Bad tasks:
|
||||
- "Set up authentication" (too vague)
|
||||
- "Make it secure" (not actionable)
|
||||
- "Handle edge cases" (which ones?)
|
||||
**Bad tasks:** Vague, not actionable
|
||||
- "Set up authentication" / "Make it secure" / "Handle edge cases"
|
||||
|
||||
If you can't specify Files + Action + Verify + Done, the task is too vague.
|
||||
</task_quality>
|
||||
|
||||
<anti_patterns>
|
||||
- Don't add story points
|
||||
- Don't estimate hours
|
||||
- Don't assign to team members
|
||||
- Don't add acceptance criteria committees
|
||||
- Don't create sub-sub-sub tasks
|
||||
|
||||
- No story points or hour estimates
|
||||
- No team assignments
|
||||
- No acceptance criteria committees
|
||||
- No sub-sub-sub tasks
|
||||
Tasks are instructions for Claude, not Jira tickets.
|
||||
</anti_patterns>
|
||||
|
||||
<success_criteria>
|
||||
Phase planning is complete when:
|
||||
- [ ] STATE.md read and project history absorbed
|
||||
- [ ] **Mandatory discovery completed** (Level 0-3 as appropriate)
|
||||
- [ ] If Level 2-3: DISCOVERY.md exists with current context
|
||||
- [ ] If Level 1: Quick verification performed via Context7
|
||||
- [ ] If RESEARCH.md exists: ecosystem knowledge incorporated into plan
|
||||
- [ ] Prior decisions, issues, and concerns synthesized
|
||||
- [ ] One or more PLAN files exist with XML structure ({phase}-{plan}-PLAN.md)
|
||||
- [ ] Each plan has: Objective, context, tasks, verification, success criteria, output
|
||||
- [ ] @context references included (including STATE.md, RESEARCH.md if exists, DISCOVERY.md if exists, relevant prior summaries)
|
||||
- [ ] Prior decisions documented in context section
|
||||
- [ ] Deferred issues being addressed are noted
|
||||
- [ ] Each plan has 2-3 tasks (scoped to ~50% context)
|
||||
- [ ] Each task has: Type, Files (if auto), Action, Verify, Done
|
||||
- [ ] Checkpoints identified and properly structured
|
||||
- [ ] Tasks are specific enough for Claude to execute
|
||||
- [ ] If RESEARCH.md exists: "don't hand-roll" items are NOT being custom-built
|
||||
- [ ] If multiple plans: logical split by subsystem/dependency/complexity
|
||||
Phase planning complete when:
|
||||
- [ ] STATE.md read, project history absorbed
|
||||
- [ ] Mandatory discovery completed (Level 0-3)
|
||||
- [ ] Prior decisions, issues, concerns synthesized
|
||||
- [ ] PLAN file(s) exist with XML structure
|
||||
- [ ] Each plan: Objective, context, tasks, verification, success criteria, output
|
||||
- [ ] @context references included (STATE, RESEARCH/DISCOVERY if exist, relevant summaries)
|
||||
- [ ] Each plan: 2-3 tasks (~50% context)
|
||||
- [ ] Each task: Type, Files (if auto), Action, Verify, Done
|
||||
- [ ] Checkpoints properly structured
|
||||
- [ ] If RESEARCH.md exists: "don't hand-roll" items NOT being custom-built
|
||||
- [ ] User knows next steps
|
||||
</success_criteria>
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user