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
2025-12-29 12:18:08 -06:00
parent 5d16432887
commit df1f138478
2 changed files with 182 additions and 1092 deletions

View File

@@ -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.

View File

@@ -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>
```