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:
@@ -1,447 +1,111 @@
|
|||||||
<scope_estimation>
|
<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 |
|
||||||
|
|
||||||
```
|
**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.
|
||||||
Context Usage │ Quality Level │ Claude's Mental State
|
|
||||||
─────────────────────────────────────────────────────────
|
|
||||||
0-30% │ ████████ PEAK │ "I can be thorough and comprehensive"
|
|
||||||
│ │ No anxiety, full detail, best work
|
|
||||||
|
|
||||||
30-50% │ ██████ GOOD │ "Still have room, maintaining quality"
|
**The rule:** Stop BEFORE quality degrades, not at context limit.
|
||||||
│ │ Engaged, confident, solid work
|
</quality_insight>
|
||||||
|
|
||||||
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>
|
|
||||||
|
|
||||||
<context_target>
|
<context_target>
|
||||||
|
|
||||||
**Plans should complete within ~50% of context usage.**
|
**Plans should complete within ~50% of context usage.**
|
||||||
|
|
||||||
Why 50% not 80%?
|
Why 50% not 80%?
|
||||||
- Huge safety buffer
|
|
||||||
- No context anxiety possible
|
- No context anxiety possible
|
||||||
- Quality maintained from start to finish
|
- Quality maintained start to finish
|
||||||
- Room for unexpected complexity
|
- Room for unexpected complexity
|
||||||
- Space for iteration and fixes
|
- If you target 80%, you've already spent 40% in degradation mode
|
||||||
|
|
||||||
**If you target 80%, you're planning for failure.** By the time you hit 80%, you've already spent 40% in degradation mode.
|
|
||||||
</context_target>
|
</context_target>
|
||||||
|
|
||||||
<task_rule>
|
<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.**
|
| Task Complexity | Tasks/Plan | Context/Task | Total |
|
||||||
|
|-----------------|------------|--------------|-------|
|
||||||
**The real measure: Stay under 50% context usage.**
|
| Simple (CRUD, config) | 3 | ~10-15% | ~30-45% |
|
||||||
|
| Complex (auth, payments) | 2 | ~20-30% | ~40-50% |
|
||||||
Task count is a proxy for context. Adjust based on task complexity:
|
| Very complex (migrations, refactors) | 1-2 | ~30-40% | ~30-50% |
|
||||||
|
|
||||||
**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
|
|
||||||
|
|
||||||
**When in doubt: Default to 2 tasks.** Better to have an extra plan than degraded quality.
|
**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>
|
</task_rule>
|
||||||
|
|
||||||
<split_signals>
|
<split_signals>
|
||||||
|
|
||||||
<always_split>
|
<always_split>
|
||||||
|
- **More than 3 tasks** - Even if tasks seem small
|
||||||
**1. More than 3 tasks**
|
- **Multiple subsystems** - DB + API + UI = separate plans
|
||||||
- Even if tasks seem small
|
- **Any task with >5 file modifications** - Split by file groups
|
||||||
- Each additional task increases degradation risk
|
- **Checkpoint + implementation work** - Checkpoints in one plan, implementation after in separate plan
|
||||||
- Split into logical groups of 2-3
|
- **Discovery + implementation** - DISCOVERY.md in one plan, implementation in another
|
||||||
|
|
||||||
**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
|
|
||||||
</always_split>
|
</always_split>
|
||||||
|
|
||||||
<consider_splitting>
|
<consider_splitting>
|
||||||
|
- Estimated >5 files modified total
|
||||||
**1. Estimated >5 files modified total**
|
- Complex domains (auth, payments, data modeling)
|
||||||
- Context from reading existing code
|
- Any uncertainty about approach
|
||||||
- Context from diffs
|
- Natural semantic boundaries (Setup -> Core -> Features)
|
||||||
- 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
|
|
||||||
</consider_splitting>
|
</consider_splitting>
|
||||||
</split_signals>
|
</split_signals>
|
||||||
|
|
||||||
<splitting_strategies>
|
<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:**
|
**By verification:** Deploy → 01: Vercel setup (checkpoint), 02: Env config (auto), 03: CI/CD (checkpoint)
|
||||||
```
|
|
||||||
- 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>
|
|
||||||
</splitting_strategies>
|
</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>
|
<anti_patterns>
|
||||||
|
**Bad - Comprehensive plan:**
|
||||||
<antipattern_comprehensive>
|
|
||||||
|
|
||||||
```
|
```
|
||||||
Plan: "Complete Authentication System"
|
Plan: "Complete Authentication System"
|
||||||
Tasks:
|
Tasks: 8 (models, migrations, API, JWT, middleware, hashing, login form, register form)
|
||||||
1. Database models
|
Result: Task 1-3 good, Task 4-5 degrading, Task 6-8 rushed
|
||||||
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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Why this fails:**
|
**Good - Atomic plans:**
|
||||||
- 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>
|
|
||||||
|
|
||||||
```
|
```
|
||||||
Split into 4 plans:
|
|
||||||
|
|
||||||
Plan 1: "Auth Database Models" (2 tasks)
|
Plan 1: "Auth Database Models" (2 tasks)
|
||||||
- Database schema (User, Session)
|
|
||||||
- Migration files
|
|
||||||
|
|
||||||
Plan 2: "Auth API Core" (3 tasks)
|
Plan 2: "Auth API Core" (3 tasks)
|
||||||
- Register endpoint
|
|
||||||
- Login endpoint
|
|
||||||
- JWT utilities
|
|
||||||
|
|
||||||
Plan 3: "Auth API Protection" (2 tasks)
|
Plan 3: "Auth API Protection" (2 tasks)
|
||||||
- Protected route middleware
|
|
||||||
- Logout endpoint
|
|
||||||
|
|
||||||
Plan 4: "Auth UI Components" (2 tasks)
|
Plan 4: "Auth UI Components" (2 tasks)
|
||||||
- Login form
|
Each: 30-40% context, peak quality, focused commits
|
||||||
- Registration form
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**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>
|
</anti_patterns>
|
||||||
|
|
||||||
<estimating_context>
|
<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>
|
**2 tasks:** Simple ~30%, Medium ~50%, Complex ~80% (split)
|
||||||
- 0-3 files modified: Small task (~10-15% context)
|
**3 tasks:** Simple ~45%, Medium ~75% (risky), Complex 120% (impossible)
|
||||||
- 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>
|
|
||||||
</estimating_context>
|
</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>
|
<summary>
|
||||||
|
|
||||||
**2-3 tasks, 50% context target:**
|
**2-3 tasks, 50% context target:**
|
||||||
- All tasks: Peak quality
|
- All tasks: Peak quality
|
||||||
- Git: Atomic, surgical commits
|
- Git: Atomic, surgical commits
|
||||||
- Quality: Consistent excellence
|
|
||||||
- Autonomous plans: Subagent execution (fresh context)
|
- Autonomous plans: Subagent execution (fresh context)
|
||||||
|
|
||||||
**The principle:** Aggressive atomicity. More plans, smaller scope, consistent quality.
|
**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
|
- Decimal phases (2.1, 2.2) = urgent insertions between integers
|
||||||
|
|
||||||
**Rules:**
|
**Rules:**
|
||||||
|
- Decimals between consecutive integers (2.1 between 2 and 3)
|
||||||
- Decimals must be between consecutive integers (2.1 between 2 and 3)
|
|
||||||
- Filesystem sorting works automatically (2 < 2.1 < 2.2 < 3)
|
- Filesystem sorting works automatically (2 < 2.1 < 2.2 < 3)
|
||||||
- Execution order follows numeric sort
|
- Directory format: `02.1-description/`, Plan format: `02.1-01-PLAN.md`
|
||||||
- Directory format: `02.1-description/` (note the dot)
|
|
||||||
- Plan format: `02.1-01-PLAN.md`
|
|
||||||
|
|
||||||
**Example:**
|
**Validation:** Integer X must exist and be complete, X+1 must exist, decimal X.Y must not exist, Y >= 1
|
||||||
|
</decimal_phase_numbering>
|
||||||
```
|
|
||||||
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>
|
|
||||||
|
|
||||||
<required_reading>
|
<required_reading>
|
||||||
**Read these files NOW:**
|
**Read these files NOW:**
|
||||||
@@ -45,140 +19,55 @@ When creating decimal phase X.Y:
|
|||||||
2. ~/.claude/get-shit-done/references/plan-format.md
|
2. ~/.claude/get-shit-done/references/plan-format.md
|
||||||
3. ~/.claude/get-shit-done/references/scope-estimation.md
|
3. ~/.claude/get-shit-done/references/scope-estimation.md
|
||||||
4. ~/.claude/get-shit-done/references/checkpoints.md
|
4. ~/.claude/get-shit-done/references/checkpoints.md
|
||||||
5. Read `.planning/ROADMAP.md`
|
5. .planning/ROADMAP.md
|
||||||
6. Read `.planning/PROJECT.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
|
**Load domain expertise from ROADMAP:**
|
||||||
|
- Parse ROADMAP.md's `## Domain Expertise` section for paths
|
||||||
**Example:** Planning a UI phase for an ISF shader macOS app:
|
- 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>`
|
||||||
- ROADMAP says: `expertise/isf-shaders`, `expertise/macos-apps`
|
</required_reading>
|
||||||
- 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>
|
|
||||||
|
|
||||||
<purpose>
|
<purpose>
|
||||||
Create an executable phase prompt (PLAN.md). This is where we get specific:
|
Create an executable phase prompt (PLAN.md). PLAN.md IS the prompt that Claude executes - not a document that gets transformed.
|
||||||
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.
|
|
||||||
</purpose>
|
</purpose>
|
||||||
|
|
||||||
<process>
|
<process>
|
||||||
|
|
||||||
<step name="load_project_state" priority="first">
|
<step name="load_project_state" priority="first">
|
||||||
Before any planning, read project state:
|
Read `.planning/STATE.md` and parse:
|
||||||
|
|
||||||
```bash
|
|
||||||
cat .planning/STATE.md 2>/dev/null
|
|
||||||
```
|
|
||||||
|
|
||||||
**If file exists:** Parse and internalize:
|
|
||||||
|
|
||||||
- Current position (which phase we're planning)
|
- Current position (which phase we're planning)
|
||||||
- Accumulated decisions (constraints on this phase)
|
- Accumulated decisions (constraints on this phase)
|
||||||
- Deferred issues (candidates for inclusion in this phase)
|
- Deferred issues (candidates for inclusion)
|
||||||
- Blockers/concerns (things this phase may need to address)
|
- Blockers/concerns (things this phase may address)
|
||||||
- Brief alignment status (are we on track?)
|
- Brief alignment status
|
||||||
|
|
||||||
**If file missing but .planning/ exists:**
|
If STATE.md missing but .planning/ exists, offer to reconstruct or continue without.
|
||||||
|
|
||||||
```
|
|
||||||
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.
|
|
||||||
</step>
|
</step>
|
||||||
|
|
||||||
<step name="load_codebase_context">
|
<step name="load_codebase_context">
|
||||||
Check if codebase map exists:
|
Check for `.planning/codebase/*.md` and load relevant documents based on phase type:
|
||||||
|
|
||||||
```bash
|
| Phase Keywords | Load These |
|
||||||
ls .planning/codebase/*.md 2>/dev/null
|
|----------------|------------|
|
||||||
```
|
| 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:**
|
Track extracted constraints for PLAN.md context section.
|
||||||
|
|
||||||
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.
|
|
||||||
</step>
|
</step>
|
||||||
|
|
||||||
<step name="identify_phase">
|
<step name="identify_phase">
|
||||||
Check roadmap for phases:
|
Check roadmap and existing phases. If multiple phases available, ask which one to plan.
|
||||||
```bash
|
|
||||||
cat .planning/ROADMAP.md
|
|
||||||
ls .planning/phases/
|
|
||||||
```
|
|
||||||
|
|
||||||
If multiple phases available, ask which one to plan.
|
**Phase number parsing:** Regex `^(\d+)(?:\.(\d+))?$` - Group 1: integer, Group 2: decimal (optional)
|
||||||
If obvious (first incomplete phase), proceed.
|
|
||||||
|
|
||||||
**Phase number parsing:**
|
**If decimal phase:** Validate integer X exists and is complete, X+1 exists in roadmap, decimal X.Y doesn't exist, Y >= 1.
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
Read any existing PLAN.md or DISCOVERY.md in the phase directory.
|
Read any existing PLAN.md or DISCOVERY.md in the phase directory.
|
||||||
</step>
|
</step>
|
||||||
@@ -186,294 +75,74 @@ Read any existing PLAN.md or DISCOVERY.md in the phase directory.
|
|||||||
<step name="mandatory_discovery">
|
<step name="mandatory_discovery">
|
||||||
**Discovery is MANDATORY unless you can prove current context exists.**
|
**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>
|
**Level 1 - Quick Verification** (2-5 min)
|
||||||
|
- Single known library, confirming syntax/version
|
||||||
````
|
|
||||||
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
|
|
||||||
- Low-risk decision (easily changed later)
|
- Low-risk decision (easily changed later)
|
||||||
- "Is X still the right choice?"
|
- Action: Context7 resolve-library-id + query-docs, no DISCOVERY.md needed
|
||||||
|
|
||||||
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:
|
|
||||||
|
|
||||||
|
**Level 2 - Standard Research** (15-30 min)
|
||||||
- Choosing between 2-3 options
|
- Choosing between 2-3 options
|
||||||
- New external integration (API, service)
|
- New external integration (API, service)
|
||||||
- Medium-risk decision
|
- Medium-risk decision
|
||||||
|
- Action: Route to workflows/discovery-phase.md depth=standard, produces DISCOVERY.md
|
||||||
|
|
||||||
Action:
|
**Level 3 - Deep Dive** (1+ hour)
|
||||||
|
|
||||||
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:
|
|
||||||
|
|
||||||
- Architectural decision with long-term impact
|
- Architectural decision with long-term impact
|
||||||
- Novel problem without clear patterns
|
- Novel problem without clear patterns
|
||||||
- High-risk, hard to change later
|
- 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
|
If roadmap flagged `Research: Likely`, Level 0 (skip) is not available.
|
||||||
2. Full discovery with cross-verification
|
|
||||||
3. DISCOVERY.md with detailed rationale and validation checkpoints
|
|
||||||
4. Return here after DISCOVERY.md created
|
|
||||||
|
|
||||||
**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."
|
For niche domains (3D, games, audio, shaders, ML), suggest `/gsd:research-phase` before plan-phase.
|
||||||
|
|
||||||
```
|
|
||||||
</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.
|
|
||||||
</step>
|
</step>
|
||||||
|
|
||||||
<step name="read_project_history">
|
<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
|
**From ISSUES.md:** Assess each open issue - relevant to this phase? Waiting long enough? Natural to address now? Blocking something?
|
||||||
- Deferred issues → Candidates for inclusion in this phase
|
|
||||||
- Blockers/concerns → Things this phase may need to address
|
|
||||||
|
|
||||||
**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
|
Track for PLAN.md context section: relevant summaries, applicable decisions, issues being addressed, concerns being verified.
|
||||||
# List all summaries from prior phases
|
</step>
|
||||||
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>
|
|
||||||
|
|
||||||
<step name="gather_phase_context">
|
<step name="gather_phase_context">
|
||||||
For this specific phase, understand:
|
Understand:
|
||||||
- What's the phase goal? (from roadmap)
|
- Phase goal (from roadmap)
|
||||||
- What exists already? (scan codebase if mid-project)
|
- What exists already (scan codebase if mid-project)
|
||||||
- What dependencies are met? (previous phases complete?)
|
- Dependencies met (previous phases complete?)
|
||||||
- Any ecosystem research? (RESEARCH.md from /gsd:research-phase)
|
- Any {phase}-RESEARCH.md (from /gsd:research-phase)
|
||||||
- Any discovery findings? (DISCOVERY.md from mandatory discovery)
|
- Any DISCOVERY.md (from mandatory discovery)
|
||||||
- Any phase context? ({phase}-CONTEXT.md from /gsd:discuss-phase)
|
- Any {phase}-CONTEXT.md (from /gsd:discuss-phase)
|
||||||
|
|
||||||
```bash
|
**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).
|
||||||
# If mid-project, understand current state
|
|
||||||
ls -la src/ 2>/dev/null
|
|
||||||
cat package.json 2>/dev/null | head -20
|
|
||||||
|
|
||||||
# Check for comprehensive ecosystem research (created by /gsd:research-phase)
|
**If CONTEXT.md exists:** Honor vision, prioritize essential, respect boundaries, incorporate specifics.
|
||||||
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 neither exist:** Suggest /gsd:research-phase for niche domains, /gsd:discuss-phase for simpler domains, or proceed with roadmap only.
|
||||||
</step>
|
</step>
|
||||||
|
|
||||||
<step name="break_into_tasks">
|
<step name="break_into_tasks">
|
||||||
Decompose the phase into tasks.
|
Decompose phase into tasks. Each task needs:
|
||||||
|
|
||||||
Each task must have:
|
|
||||||
|
|
||||||
- **Type**: auto, checkpoint:human-verify, checkpoint:decision (human-action rarely needed)
|
- **Type**: auto, checkpoint:human-verify, checkpoint:decision (human-action rarely needed)
|
||||||
- **Task name**: Clear, action-oriented
|
- **Task name**: Clear, action-oriented
|
||||||
- **Files**: Which files created/modified (for auto tasks)
|
- **Files**: Which files created/modified (for auto tasks)
|
||||||
@@ -481,168 +150,62 @@ Each task must have:
|
|||||||
- **Verify**: How to prove it worked
|
- **Verify**: How to prove it worked
|
||||||
- **Done**: Acceptance criteria
|
- **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):
|
See ~/.claude/get-shit-done/references/checkpoints.md for checkpoint structure.
|
||||||
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.
|
|
||||||
</step>
|
</step>
|
||||||
|
|
||||||
<step name="estimate_scope">
|
<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
|
**If scope appropriate (2-3 tasks, single subsystem, <5 files/task):** Proceed to confirm_breakdown.
|
||||||
- Multiple subsystems (DB + API + UI = separate plans)
|
|
||||||
- > 5 files modified in any single task
|
|
||||||
- Complex domains (auth, payments, data modeling)
|
|
||||||
|
|
||||||
**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):**
|
**Each plan must be:** 2-3 tasks max, ~50% context target, independently committable.
|
||||||
Proceed to confirm_breakdown for a single plan.
|
|
||||||
|
|
||||||
**If scope is large (>3 tasks):**
|
**Autonomous optimization:** No checkpoints → subagent (fresh context). Has checkpoints → main context. Group autonomous work together.
|
||||||
Split into multiple plans by:
|
|
||||||
|
|
||||||
- Subsystem (01-01: Database, 01-02: API, 01-03: UI, 01-04: Frontend)
|
See ~/.claude/get-shit-done/references/scope-estimation.md for complete guidance.
|
||||||
- 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.
|
|
||||||
</step>
|
</step>
|
||||||
|
|
||||||
<step name="confirm_breakdown">
|
<step name="confirm_breakdown">
|
||||||
<config-check>
|
|
||||||
```bash
|
|
||||||
cat .planning/config.json 2>/dev/null
|
|
||||||
```
|
|
||||||
</config-check>
|
|
||||||
|
|
||||||
<if mode="yolo">
|
<if mode="yolo">
|
||||||
```
|
Auto-approve and proceed to write_phase_prompt.
|
||||||
⚡ 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.
|
|
||||||
</if>
|
</if>
|
||||||
|
|
||||||
<if mode="interactive" OR="custom with gates.confirm_breakdown true">
|
<if mode="interactive">
|
||||||
Present the breakdown inline and wait for confirmation:
|
Present breakdown inline:
|
||||||
|
|
||||||
**If single plan (2-3 tasks):**
|
|
||||||
|
|
||||||
```
|
```
|
||||||
Here's the proposed breakdown for Phase [X]:
|
Phase [X] breakdown:
|
||||||
|
|
||||||
### Tasks (single plan: {phase}-01-PLAN.md)
|
### Tasks ({phase}-01-PLAN.md)
|
||||||
1. [Task name] - [brief description] [type: auto/checkpoint]
|
1. [Task] - [brief] [type]
|
||||||
2. [Task name] - [brief description] [type: auto/checkpoint]
|
2. [Task] - [brief] [type]
|
||||||
[3. [Task name] - [brief description] [type: auto/checkpoint]] (optional 3rd task if small)
|
|
||||||
|
|
||||||
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.
|
||||||
|
|
||||||
```
|
Wait for confirmation. If "adjust": revise. If "start over": return to gather_phase_context.
|
||||||
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.
|
|
||||||
</if>
|
</if>
|
||||||
</step>
|
</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">
|
<step name="decision_gate">
|
||||||
<if mode="yolo">
|
<if mode="yolo">Auto-approve and proceed.</if>
|
||||||
```
|
<if mode="interactive">
|
||||||
⚡ Auto-approved: Create phase prompt for Phase [X]
|
Ask: "Ready to create the phase prompt, or ask more questions?"
|
||||||
```
|
Options: Create phase prompt / Ask more questions / Let me add context
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
Loop until "Create phase prompt" selected.
|
Loop until "Create phase prompt" selected.
|
||||||
</if>
|
</if>
|
||||||
</step>
|
</step>
|
||||||
@@ -650,165 +213,41 @@ Loop until "Create phase prompt" selected.
|
|||||||
<step name="write_phase_prompt">
|
<step name="write_phase_prompt">
|
||||||
Use template from `~/.claude/get-shit-done/templates/phase-prompt.md`.
|
Use template from `~/.claude/get-shit-done/templates/phase-prompt.md`.
|
||||||
|
|
||||||
**If single plan:**
|
**Single plan:** Write to `.planning/phases/XX-name/{phase}-01-PLAN.md`
|
||||||
Write to `.planning/phases/XX-name/{phase}-01-PLAN.md`
|
|
||||||
|
|
||||||
**If multiple plans:**
|
**Multiple plans:** Write separate files ({phase}-01-PLAN.md, {phase}-02-PLAN.md, etc.)
|
||||||
Write multiple files:
|
|
||||||
|
|
||||||
- `.planning/phases/XX-name/{phase}-01-PLAN.md`
|
Each plan follows template structure with:
|
||||||
- `.planning/phases/XX-name/{phase}-02-PLAN.md`
|
- Frontmatter (phase, plan, type, domain)
|
||||||
- `.planning/phases/XX-name/{phase}-03-PLAN.md`
|
- 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:
|
For multi-plan phases: each plan has focused scope, references previous plan summaries, last plan's success criteria includes "Phase X complete".
|
||||||
|
</step>
|
||||||
```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>
|
|
||||||
|
|
||||||
<step name="offer_next">
|
<step name="offer_next">
|
||||||
**If single plan:**
|
|
||||||
```
|
```
|
||||||
Phase plan created: .planning/phases/XX-name/{phase}-01-PLAN.md
|
Phase plan created: .planning/phases/XX-name/{phase}-01-PLAN.md
|
||||||
[X] tasks defined.
|
[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`
|
`/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:**
|
**Also available:**
|
||||||
- Review/adjust tasks before executing
|
- Review/adjust tasks before executing
|
||||||
|
[If multiple plans: - View all plans: `ls .planning/phases/XX-name/*-PLAN.md`]
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
**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`
|
|
||||||
|
|
||||||
---
|
---
|
||||||
```
|
```
|
||||||
@@ -817,48 +256,35 @@ Total: [X] tasks across [Y] focused plans.
|
|||||||
</process>
|
</process>
|
||||||
|
|
||||||
<task_quality>
|
<task_quality>
|
||||||
Good tasks:
|
**Good tasks:** Specific files, actions, verification
|
||||||
- "Add User model to Prisma schema with email, passwordHash, createdAt"
|
- "Add User model to Prisma schema with email, passwordHash, createdAt"
|
||||||
- "Create POST /api/auth/login endpoint with bcrypt validation"
|
- "Create POST /api/auth/login endpoint with bcrypt validation"
|
||||||
- "Add protected route middleware checking JWT in cookies"
|
|
||||||
|
|
||||||
Bad tasks:
|
**Bad tasks:** Vague, not actionable
|
||||||
- "Set up authentication" (too vague)
|
- "Set up authentication" / "Make it secure" / "Handle edge cases"
|
||||||
- "Make it secure" (not actionable)
|
|
||||||
- "Handle edge cases" (which ones?)
|
|
||||||
|
|
||||||
If you can't specify Files + Action + Verify + Done, the task is too vague.
|
If you can't specify Files + Action + Verify + Done, the task is too vague.
|
||||||
</task_quality>
|
</task_quality>
|
||||||
|
|
||||||
<anti_patterns>
|
<anti_patterns>
|
||||||
- Don't add story points
|
- No story points or hour estimates
|
||||||
- Don't estimate hours
|
- No team assignments
|
||||||
- Don't assign to team members
|
- No acceptance criteria committees
|
||||||
- Don't add acceptance criteria committees
|
- No sub-sub-sub tasks
|
||||||
- Don't create sub-sub-sub tasks
|
|
||||||
|
|
||||||
Tasks are instructions for Claude, not Jira tickets.
|
Tasks are instructions for Claude, not Jira tickets.
|
||||||
</anti_patterns>
|
</anti_patterns>
|
||||||
|
|
||||||
<success_criteria>
|
<success_criteria>
|
||||||
Phase planning is complete when:
|
Phase planning complete when:
|
||||||
- [ ] STATE.md read and project history absorbed
|
- [ ] STATE.md read, project history absorbed
|
||||||
- [ ] **Mandatory discovery completed** (Level 0-3 as appropriate)
|
- [ ] Mandatory discovery completed (Level 0-3)
|
||||||
- [ ] If Level 2-3: DISCOVERY.md exists with current context
|
- [ ] Prior decisions, issues, concerns synthesized
|
||||||
- [ ] If Level 1: Quick verification performed via Context7
|
- [ ] PLAN file(s) exist with XML structure
|
||||||
- [ ] If RESEARCH.md exists: ecosystem knowledge incorporated into plan
|
- [ ] Each plan: Objective, context, tasks, verification, success criteria, output
|
||||||
- [ ] Prior decisions, issues, and concerns synthesized
|
- [ ] @context references included (STATE, RESEARCH/DISCOVERY if exist, relevant summaries)
|
||||||
- [ ] One or more PLAN files exist with XML structure ({phase}-{plan}-PLAN.md)
|
- [ ] Each plan: 2-3 tasks (~50% context)
|
||||||
- [ ] Each plan has: Objective, context, tasks, verification, success criteria, output
|
- [ ] Each task: Type, Files (if auto), Action, Verify, Done
|
||||||
- [ ] @context references included (including STATE.md, RESEARCH.md if exists, DISCOVERY.md if exists, relevant prior summaries)
|
- [ ] Checkpoints properly structured
|
||||||
- [ ] Prior decisions documented in context section
|
- [ ] If RESEARCH.md exists: "don't hand-roll" items NOT being custom-built
|
||||||
- [ ] 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
|
|
||||||
- [ ] User knows next steps
|
- [ ] User knows next steps
|
||||||
</success_criteria>
|
</success_criteria>
|
||||||
```
|
|
||||||
|
|||||||
Reference in New Issue
Block a user