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