diff --git a/agents/gsd-verifier.md b/agents/gsd-verifier.md index 0821bd369..0d62fd176 100644 --- a/agents/gsd-verifier.md +++ b/agents/gsd-verifier.md @@ -462,48 +462,51 @@ Some things can't be verified programmatically: score = (verified_truths / total_truths) ``` -## Step 10: Generate Fix Plans (If Gaps Found) +## Step 10: Structure Gap Output (If Gaps Found) -Group related gaps into fix plans: +When gaps are found, structure them for consumption by `/gsd:plan-phase --gaps`. -1. **Identify gap clusters:** +**Output structured gaps in YAML frontmatter:** - - API stub + component not wired → "Wire frontend to backend" - - Multiple artifacts missing → "Complete core implementation" - - Wiring issues only → "Connect existing components" - -2. **Generate plan recommendations:** - -```markdown -### {phase}-{next}-PLAN.md: {Fix Name} - -**Objective:** {What this fixes} - -**Tasks:** - -1. {Task to fix gap 1} - - - Files: {files to modify} - - Action: {specific fix} - - Verify: {how to confirm fix} - -2. {Task to fix gap 2} - -3. Re-verify phase goal - -**Estimated scope:** {Small / Medium} +```yaml +--- +phase: XX-name +verified: YYYY-MM-DDTHH:MM:SSZ +status: gaps_found +score: N/M must-haves verified +gaps: + - truth: "User can see existing messages" + status: failed + reason: "Chat.tsx exists but doesn't fetch from API" + artifacts: + - path: "src/components/Chat.tsx" + issue: "No useEffect with fetch call" + missing: + - "API call in useEffect to /api/chat" + - "State for storing fetched messages" + - "Render messages array in JSX" + - truth: "User can send a message" + status: failed + reason: "Form exists but onSubmit is stub" + artifacts: + - path: "src/components/Chat.tsx" + issue: "onSubmit only calls preventDefault()" + missing: + - "POST request to /api/chat" + - "Add new message to state after success" +--- ``` -3. **Keep plans focused:** +**Gap structure:** +- `truth`: The observable truth that failed verification +- `status`: failed | partial +- `reason`: Brief explanation of why it failed +- `artifacts`: Which files have issues and what's wrong +- `missing`: Specific things that need to be added/fixed - - 2-3 tasks per plan - - Single concern per plan - - Include verification task +The planner (`/gsd:plan-phase --gaps`) reads this gap analysis and creates appropriate plans. -4. **Order by dependency:** - - Fix missing artifacts before wiring - - Fix stubs before integration - - Verify after all fixes +**Group related gaps by concern** when possible — if multiple truths fail because of the same root cause (e.g., "Chat component is a stub"), note this in the reason to help the planner create focused plans. @@ -519,6 +522,20 @@ phase: XX-name verified: YYYY-MM-DDTHH:MM:SSZ status: passed | gaps_found | human_needed score: N/M must-haves verified +gaps: # Only include if status: gaps_found + - truth: "Observable truth that failed" + status: failed + reason: "Why it failed" + artifacts: + - path: "src/path/to/file.tsx" + issue: "What's wrong with this file" + missing: + - "Specific thing to add/fix" + - "Another specific thing" +human_verification: # Only include if status: human_needed + - test: "What to do" + expected: "What should happen" + why_human: "Why can't verify programmatically" --- # Phase {X}: {Name} Verification Report @@ -561,15 +578,11 @@ score: N/M must-haves verified ### Human Verification Required -{Items needing human testing} +{Items needing human testing — detailed format for user} ### Gaps Summary -{Critical and non-critical gaps} - -### Recommended Fix Plans - -{If gaps_found, include fix plan recommendations} +{Narrative summary of what's missing and why} --- @@ -597,17 +610,14 @@ All must-haves verified. Phase goal achieved. Ready to proceed. ### Gaps Found -{N} critical gaps blocking goal achievement: +{N} gaps blocking goal achievement: -1. {Gap 1 summary} -2. {Gap 2 summary} +1. **{Truth 1}** — {reason} + - Missing: {what needs to be added} +2. **{Truth 2}** — {reason} + - Missing: {what needs to be added} -### Recommended Fixes - -{N} fix plans recommended: - -1. {phase}-{next}-PLAN.md: {name} -2. {phase}-{next+1}-PLAN.md: {name} +Structured gaps in VERIFICATION.md frontmatter for `/gsd:plan-phase --gaps`. {If human_needed:} @@ -615,8 +625,10 @@ All must-haves verified. Phase goal achieved. Ready to proceed. {N} items need human testing: -1. {Item 1} -2. {Item 2} +1. **{Test name}** — {what to do} + - Expected: {what should happen} +2. **{Test name}** — {what to do} + - Expected: {what should happen} Automated checks passed. Awaiting human verification. ``` @@ -631,7 +643,7 @@ Automated checks passed. Awaiting human verification. **DO NOT skip key link verification.** This is where 80% of stubs hide. The pieces exist but aren't connected. -**DO generate fix plans if gaps found.** Don't just report "this is broken" — recommend specific fix plans with tasks. +**Structure gaps in YAML frontmatter.** The planner (`/gsd:plan-phase --gaps`) creates plans from your analysis. **DO flag for human verification when uncertain.** If you can't verify programmatically (visual, real-time, external service), say so explicitly. @@ -726,7 +738,7 @@ return
No messages
// Always shows "no messages" - [ ] Anti-patterns scanned and categorized - [ ] Human verification items identified - [ ] Overall status determined -- [ ] Fix plans generated (if gaps_found) +- [ ] Gaps structured in YAML frontmatter (if gaps_found) - [ ] VERIFICATION.md created with complete report - [ ] Results returned to orchestrator (NOT committed) - + diff --git a/commands/gsd/execute-phase.md b/commands/gsd/execute-phase.md index 4bd969544..d847b6e76 100644 --- a/commands/gsd/execute-phase.md +++ b/commands/gsd/execute-phase.md @@ -65,9 +65,10 @@ Phase: $ARGUMENTS - Spawn `gsd-verifier` subagent with phase directory and goal - Verifier checks must_haves against actual codebase (not SUMMARY claims) - Creates VERIFICATION.md with detailed report - - If gaps found: create fix plans, execute, re-verify (max 3 cycles) - - If human verification needed: present items to user - - Block until verification passes or user approves + - Route by status: + - `passed` → continue to step 7 + - `human_needed` → present items, get approval or feedback + - `gaps_found` → present gaps, offer `/gsd:plan-phase {X} --gaps` 7. **Update roadmap and state** - Update ROADMAP.md, STATE.md @@ -93,25 +94,23 @@ Phase: $ARGUMENTS **MANDATORY: Present copy/paste-ready next command.** -After phase completes, determine what's next: +After verification completes, route based on status: -**Step 1: Check milestone status** - -Read ROADMAP.md. Find current phase number and highest phase in milestone. - -| Condition | Action | -|-----------|--------| -| current < highest | More phases → Route A | -| current = highest | Milestone complete → Route B | +| Status | Route | +|--------|-------| +| `gaps_found` | Route C (gap closure) | +| `human_needed` | Present checklist, then re-route based on approval | +| `passed` + more phases | Route A (next phase) | +| `passed` + last phase | Route B (milestone complete) | --- -**Route A: More phases remain in milestone** +**Route A: Phase verified, more phases remain** ``` ## ✓ Phase {Z}: {Name} Complete -All {Y} plans finished. +All {Y} plans finished. Phase goal verified. --- @@ -135,14 +134,14 @@ All {Y} plans finished. --- -**Route B: Milestone complete** +**Route B: Phase verified, milestone complete** ``` 🎉 MILESTONE COMPLETE! ## ✓ Phase {Z}: {Name} Complete -All {N} phases finished. +All {N} phases finished. All goals verified. --- @@ -162,6 +161,46 @@ All {N} phases finished. --- ``` + +--- + +**Route C: Gaps found — need additional planning** + +``` +## ⚠ Phase {Z}: {Name} — Gaps Found + +**Score:** {N}/{M} must-haves verified +**Report:** .planning/phases/{phase_dir}/{phase}-VERIFICATION.md + +### What's Missing + +{Extract gap summaries from VERIFICATION.md} + +--- + +## ▶ Next Up + +**Plan gap closure** — create additional plans to complete the phase + +`/gsd:plan-phase {Z} --gaps` + +`/clear` first → fresh context window + +--- + +**Also available:** +- `cat .planning/phases/{phase_dir}/{phase}-VERIFICATION.md` — see full report +- `/gsd:verify-work {Z}` — manual testing before planning + +--- +``` + +After user runs `/gsd:plan-phase {Z} --gaps`: +1. Planner reads VERIFICATION.md gaps +2. Creates plans 04, 05, etc. to close gaps +3. User runs `/gsd:execute-phase {Z}` again +4. Execute-phase runs incomplete plans (04, 05...) +5. Verifier runs again → loop until passed diff --git a/commands/gsd/plan-phase.md b/commands/gsd/plan-phase.md index 1699abdc0..a8ff00094 100644 --- a/commands/gsd/plan-phase.md +++ b/commands/gsd/plan-phase.md @@ -1,7 +1,7 @@ --- name: gsd:plan-phase description: Create detailed execution plan for a phase (PLAN.md) -argument-hint: "[phase]" +argument-hint: "[phase] [--gaps]" allowed-tools: - Read - Bash @@ -18,6 +18,9 @@ Create executable phase prompt with discovery, context injection, and task break Purpose: Break down roadmap phases into concrete, executable PLAN.md files that Claude can execute. Output: One or more PLAN.md files in the phase directory (.planning/phases/XX-name/{phase}-{plan}-PLAN.md) + +**Gap closure mode (`--gaps` flag):** +When invoked with `--gaps`, plans address gaps identified by the verifier. Load VERIFICATION.md, create plans to close specific gaps. @@ -33,6 +36,7 @@ Output: One or more PLAN.md files in the phase directory (.planning/phases/XX-na Phase number: $ARGUMENTS (optional - auto-detects next unplanned phase if not provided) +Gap closure mode: `--gaps` flag triggers gap closure workflow **Load project state first:** @.planning/STATE.md @@ -59,19 +63,33 @@ Check for and read `.planning/phases/XX-name/{phase}-CONTEXT.md` - contains rese **Load codebase context if exists:** Check for `.planning/codebase/` and load relevant documents based on phase type. + +**If --gaps flag present, also load:** +@.planning/phases/XX-name/{phase}-VERIFICATION.md — contains structured gaps in YAML frontmatter 1. Check .planning/ directory exists (error if not - user should run /gsd:new-project) -2. If phase number provided via $ARGUMENTS, validate it exists in roadmap -3. If no phase number, detect next unplanned phase from roadmap -4. Follow plan-phase.md workflow: +2. Parse arguments: extract phase number and check for `--gaps` flag +3. If phase number provided, validate it exists in roadmap +4. If no phase number, detect next unplanned phase from roadmap + +**Standard mode (no --gaps flag):** +5. Follow plan-phase.md workflow: - Load project state and accumulated decisions - Perform mandatory discovery (Level 0-3 as appropriate) - Read project history (prior decisions, issues, concerns) - Break phase into tasks - Estimate scope and split into multiple plans if needed - Create PLAN.md file(s) with executable structure + +**Gap closure mode (--gaps flag):** +5. Follow plan-phase.md workflow with gap_closure_mode: + - Load VERIFICATION.md and parse `gaps:` YAML from frontmatter + - Read existing SUMMARYs to understand what's already built + - Create tasks from gaps (each gap.missing item → task candidates) + - Number plans sequentially after existing (if 01-03 exist, create 04, 05...) + - Create PLAN.md file(s) focused on closing specific gaps diff --git a/get-shit-done/workflows/execute-phase.md b/get-shit-done/workflows/execute-phase.md index 9d60e53c4..b2752a10a 100644 --- a/get-shit-done/workflows/execute-phase.md +++ b/get-shit-done/workflows/execute-phase.md @@ -3,9 +3,7 @@ Execute all plans in a phase using wave-based parallel execution. Orchestrator s -The orchestrator's job is coordination, not execution. Orchestrator discovers plans, groups into waves, spawns `gsd-executor` agents, handles checkpoints, collects results. - -**Subagent:** `gsd-executor` — dedicated plan execution agent with all execution logic baked in. +The orchestrator's job is coordination, not execution. Each subagent loads the full execute-plan context itself. Orchestrator discovers plans, analyzes dependencies, groups into waves, spawns agents, handles checkpoints, collects results. @@ -152,34 +150,43 @@ Execute each wave in sequence. Autonomous plans within a wave run in parallel. - Bad: "Executing terrain generation plan" - Good: "Procedural terrain generator using Perlin noise — creates height maps, biome zones, and collision meshes. Required before vehicle physics can interact with ground." -2. **Spawn all agents in wave simultaneously using gsd-executor:** +2. **Spawn all autonomous agents in wave simultaneously:** - Use Task tool with multiple parallel calls. Each agent is `gsd-executor` with minimal prompt: + Use Task tool with multiple parallel calls. Each agent gets prompt from subagent-task-prompt template: ``` - Task( - prompt="Execute plan at {plan_path} + + Execute plan {plan_number} of phase {phase_number}-{phase_name}. -Plan: @{plan_path} -Project state: @.planning/STATE.md -Config: @.planning/config.json (if exists)", - subagent_type="gsd-executor", - description="Execute {phase}-{plan}" - ) + Commit each task atomically. Create SUMMARY.md. Update STATE.md. + + + + @~/.claude/get-shit-done/workflows/execute-plan.md + @~/.claude/get-shit-done/templates/summary.md + @~/.claude/get-shit-done/references/checkpoints.md + @~/.claude/get-shit-done/references/tdd.md + + + + Plan: @{plan_path} + Project state: @.planning/STATE.md + Config: @.planning/config.json (if exists) + + + + - [ ] All tasks executed + - [ ] Each task committed individually + - [ ] SUMMARY.md created in plan directory + - [ ] STATE.md updated with position and decisions + ``` - The `gsd-executor` subagent has all execution logic baked in: - - Deviation rules - - Checkpoint protocols - - Commit formatting - - Summary creation - - State updates - - No template filling needed. Just pass the plan path. +2. **Wait for all agents in wave to complete:** Task tool blocks until each agent finishes. All parallel agents return together. -4. **Report completion and what was built:** +3. **Report completion and what was built:** For each completed agent: - Verify SUMMARY.md exists at expected path @@ -208,7 +215,7 @@ Config: @.planning/config.json (if exists)", - Bad: "Wave 2 complete. Proceeding to Wave 3." - Good: "Terrain system complete — 3 biome types, height-based texturing, physics collision meshes. Vehicle physics (Wave 3) can now reference ground surfaces." -5. **Handle failures:** +4. **Handle failures:** If any agent in wave fails: - Report which plan failed and why @@ -216,11 +223,11 @@ Config: @.planning/config.json (if exists)", - If continue: proceed to next wave (dependent plans may also fail) - If stop: exit with partial completion report -6. **Execute checkpoint plans between waves:** +5. **Execute checkpoint plans between waves:** See `` for details. -7. **Proceed to next wave** +6. **Proceed to next wave** @@ -231,22 +238,15 @@ Plans with `autonomous: false` require user interaction. **Execution flow for checkpoint plans:** -1. **Spawn gsd-executor for checkpoint plan:** +1. **Spawn agent for checkpoint plan:** ``` - Task( - prompt="Execute plan at {plan_path} - -Plan: @{plan_path} -Project state: @.planning/STATE.md", - subagent_type="gsd-executor", - description="Execute {phase}-{plan}" - ) + Task(prompt="{subagent-task-prompt}", subagent_type="general-purpose") ``` 2. **Agent runs until checkpoint:** - Executes auto tasks normally - - Reaches checkpoint task or auth gate - - Agent returns with structured checkpoint (format baked into gsd-executor) + - Reaches checkpoint task (e.g., `type="checkpoint:human-verify"`) or auth gate + - Agent returns with structured checkpoint (see checkpoint-return.md template) 3. **Agent return includes (structured format):** - Completed Tasks table with commit hashes and files @@ -275,29 +275,20 @@ Project state: @.planning/STATE.md", 6. **Spawn continuation agent (NOT resume):** - Spawn fresh `gsd-executor` with continuation context: + Use the continuation-prompt.md template: ``` Task( - prompt="Continue executing plan at {plan_path} - - -{completed_tasks_table from checkpoint return} - - - -Resume from: Task {N} - {task_name} -User response: {user_response} -{resume_instructions based on checkpoint type} - - -Plan: @{plan_path} -Project state: @.planning/STATE.md", - subagent_type="gsd-executor", - description="Continue {phase}-{plan}" + prompt=filled_continuation_template, + subagent_type="general-purpose" ) ``` - The `gsd-executor` has continuation handling baked in — it will verify previous commits and resume correctly. + Fill template with: + - `{completed_tasks_table}`: From agent's checkpoint return + - `{resume_task_number}`: Current task from checkpoint + - `{resume_task_name}`: Current task name from checkpoint + - `{user_response}`: What user provided + - `{resume_instructions}`: Based on checkpoint type (see continuation-prompt.md) 7. **Continuation agent executes:** - Verifies previous commits exist @@ -351,150 +342,101 @@ After all waves complete, aggregate results: -**Verify the phase GOAL was achieved, not just that tasks completed.** +Verify phase achieved its GOAL, not just completed its TASKS. -This step catches the common failure: tasks done but goal not met (stubs, placeholders, unwired code). - -**1. Spawn gsd-verifier subagent:** +**Spawn verifier:** ``` Task( - prompt="Verify phase {phase_number} goal achievement + prompt="Verify phase {phase_number} goal achievement. -Phase: {phase_number} - {phase_name} -Phase goal: {phase_goal_from_roadmap} -Phase directory: @.planning/phases/{phase_dir}/ +Phase directory: {phase_dir} +Phase goal: {goal from ROADMAP.md} -Project context: -@.planning/ROADMAP.md -@.planning/REQUIREMENTS.md (if exists)", - subagent_type="gsd-verifier", - description="Verify phase {phase_number}" +Check must_haves against actual codebase. Create VERIFICATION.md. +Verify what actually exists in the code.", + subagent_type="gsd-verifier" ) ``` -The `gsd-verifier` subagent has all verification logic baked in: -- Establishes must-haves (from frontmatter or derived) -- Verifies observable truths against codebase -- Checks artifacts exist and are substantive (not stubs) -- Traces key links (wiring between components) -- Scans for anti-patterns -- Creates VERIFICATION.md report -- Returns status to orchestrator - -**2. Verification subagent returns** with status and report path. - -**3. Handle verification result:** - -**If status = "passed":** -``` -## ✓ Phase Verification Passed - -All {N} must-haves verified: -- {truth 1} ✓ -- {truth 2} ✓ -- {truth 3} ✓ - -Phase goal achieved. Proceeding to update roadmap. -``` - -Continue to update_roadmap step. - -**If status = "gaps_found":** -``` -## ⚠️ Phase Verification Found Gaps - -{M} of {N} must-haves incomplete: - -| Must-Have | Status | Issue | -|-----------|--------|-------| -| {truth 1} | ✓ VERIFIED | - | -| {truth 2} | ✗ FAILED | API route returns placeholder | -| {truth 3} | ✗ FAILED | Component not wired to API | - -### Recommended Fix Plans - -1. **{phase}-{next}-PLAN.md**: {description} -2. **{phase}-{next+1}-PLAN.md**: {description} - -Creating fix plans and executing... -``` - -Then: -1. Generate fix PLAN.md files from recommendations -2. Execute fix plans (loop back to execute_waves) -3. Re-verify (loop back to verify_phase_goal) -4. Repeat until all must-haves pass - -**If status = "human_needed":** -``` -## 👤 Human Verification Required - -Automated checks passed. These items need manual testing: - -### 1. {Test Name} -**Test:** {what to do} -**Expected:** {what should happen} - -### 2. {Test Name} -**Test:** {what to do} -**Expected:** {what should happen} - -After testing, type "verified" or describe issues found. -``` - -Wait for user response: -- "verified" / "pass" / "ok" → Continue to update_roadmap -- Description of issues → Generate fix plans, execute, re-verify - -**4. Fix plan generation:** - -When gaps are found, generate fix plans: +**Read verification status:** ```bash -# Create fix plan from verification recommendations -NEXT_PLAN_NUM=$(ls "$PHASE_DIR"/*-PLAN.md | wc -l) -NEXT_PLAN_NUM=$((NEXT_PLAN_NUM + 1)) +grep "^status:" "$PHASE_DIR"/*-VERIFICATION.md | cut -d: -f2 | tr -d ' ' ``` -Fix plans: -- Use standard PLAN.md template -- Include must_haves (same as original, for re-verification) -- Tasks target specific gaps (not entire feature) -- Wave 99 (runs after all original plans) +**Route by status:** -**5. Re-verification loop:** +| Status | Action | +|--------|--------| +| `passed` | Continue to update_roadmap | +| `human_needed` | Present items to user, get approval or feedback | +| `gaps_found` | Present gap summary, offer `/gsd:plan-phase {phase} --gaps` | -After fix plans execute: -1. Spawn verification subagent again -2. Check same must-haves -3. If still gaps → more fix plans -4. If passed → continue +**If passed:** -Limit: 3 fix cycles. If still failing after 3 rounds, present to user: -``` -## ⚠️ Verification Still Failing After 3 Fix Attempts +Phase goal verified. Proceed to update_roadmap. -Remaining gaps: -- {gap 1} -- {gap 2} +**If human_needed:** -Options: -1. Continue anyway (manual fixes later) -2. Stop and investigate +```markdown +## ✓ Phase {X}: {Name} — Human Verification Required + +All automated checks passed. {N} items need human testing: + +### Human Verification Checklist + +{Extract from VERIFICATION.md human_verification section} + +--- + +**After testing:** +- "approved" → continue to update_roadmap +- Report issues → will route to gap closure planning ``` -**Why this matters:** +If user approves → continue to update_roadmap. +If user reports issues → treat as gaps_found. -Without verification: -- Phase 3 "complete" but chat doesn't work -- Phase 4 builds on broken foundation -- Phase 8: "nothing works, start over" +**If gaps_found:** -With verification: -- Phase 3 verified before moving on -- Gaps caught and fixed immediately -- Each phase delivers real value +Present gaps and offer next command: + +```markdown +## ⚠ Phase {X}: {Name} — Gaps Found + +**Score:** {N}/{M} must-haves verified +**Report:** {phase_dir}/{phase}-VERIFICATION.md + +### What's Missing + +{Extract gap summaries from VERIFICATION.md gaps section} + +--- + +## ▶ Next Up + +**Plan gap closure** — create additional plans to complete the phase + +`/gsd:plan-phase {X} --gaps` + +`/clear` first → fresh context window + +--- + +**Also available:** +- `cat {phase_dir}/{phase}-VERIFICATION.md` — see full report +- `/gsd:verify-work {X}` — manual testing before planning +``` + +User runs `/gsd:plan-phase {X} --gaps` which: +1. Reads VERIFICATION.md gaps +2. Creates additional plans (04, 05, etc.) to close gaps +3. User then runs `/gsd:execute-phase {X}` again +4. Execute-phase runs incomplete plans (04-05) +5. Verifier runs again after new plans complete + +User stays in control at each decision point. @@ -544,21 +486,20 @@ All {N} phases executed. Orchestrator context usage: ~10-15% - Read plan frontmatter (small) -- Group by wave (logic, no heavy reads) -- Spawn Task calls with minimal prompts +- Analyze dependencies (logic, no heavy reads) +- Fill template strings +- Spawn Task calls - Collect results -Each `gsd-executor` subagent: Fresh 200k context -- Execution logic baked into subagent prompt (cached) -- Only plan-specific context varies +Each subagent: Fresh 200k context +- Loads full execute-plan workflow +- Loads templates, references - Executes plan with full capacity - Creates SUMMARY, commits -**Prompt caching benefit:** The `gsd-executor` subagent prompt is stable across all invocations. Only the plan path varies. 90% cost reduction on cached portion. - **No polling.** Task tool blocks until completion. No TaskOutput loops. -**No context bleed.** Orchestrator never reads execution internals. Just paths and results. +**No context bleed.** Orchestrator never reads workflow internals. Just paths and results. diff --git a/get-shit-done/workflows/plan-phase.md b/get-shit-done/workflows/plan-phase.md index a06020831..d27c6d5fa 100644 --- a/get-shit-done/workflows/plan-phase.md +++ b/get-shit-done/workflows/plan-phase.md @@ -100,6 +100,114 @@ If multiple phases available, ask which one to plan. If obvious (first incomplet **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. + +**Check for --gaps flag:** +If `--gaps` present in arguments, switch to gap_closure_mode (see ``). + + + +**Triggered by `--gaps` flag.** Plans address verification gaps. + +**1. Load VERIFICATION.md:** + +```bash +PHASE_DIR=$(ls -d .planning/phases/${PHASE_ARG}* 2>/dev/null | head -1) +cat "$PHASE_DIR"/*-VERIFICATION.md +``` + +**2. Parse gaps from YAML frontmatter:** + +Extract `gaps:` array. Each gap has: +- `truth`: The observable behavior that failed +- `reason`: Why it failed +- `artifacts`: Files with issues +- `missing`: Specific things to add/fix + +**3. Load existing SUMMARYs:** + +```bash +ls "$PHASE_DIR"/*-SUMMARY.md +``` + +Understand what's already built. Gap closure plans reference existing work. + +**4. Find next plan number:** + +```bash +# Get highest existing plan number +ls "$PHASE_DIR"/*-PLAN.md | sort -V | tail -1 +``` + +If plans 01, 02, 03 exist, next is 04. + +**5. Group gaps into plans:** + +Cluster related gaps by: +- Same artifact (multiple issues in Chat.tsx → one plan) +- Same concern (fetch + render → one "wire frontend" plan) +- Dependency order (can't wire if artifact is stub → fix stub first) + +**6. Create gap closure tasks:** + +For each gap: +```xml + + {artifact.path} + + {For each item in gap.missing:} + - {missing item} + + Reference existing code: {from SUMMARYs} + Gap reason: {gap.reason} + + {How to confirm gap is closed} + {Observable truth now achievable} + +``` + +**7. Write PLAN.md files:** + +Use standard template but note gap closure context: + +```yaml +--- +phase: XX-name +plan: NN # Sequential after existing +type: execute +wave: 1 # Gap closures typically single wave +depends_on: [] # Usually independent of each other +files_modified: [...] +autonomous: true +gap_closure: true # Flag for tracking +--- +``` + +**9. Present gap closure summary:** + +```markdown +## Gap Closure Plans Created + +**Phase {X}: {Name}** — closing {N} gaps + +| Plan | Gaps Addressed | Files | +|------|----------------|-------| +| {phase}-04 | {gap truths} | {files} | +| {phase}-05 | {gap truths} | {files} | + +--- + +## ▶ Next Up + +**Execute gap closure plans** + +`/gsd:execute-phase {X}` + +`/clear` first → fresh context window + +--- +``` + +**Skip directly to git_commit step after creating plans.** @@ -240,120 +348,6 @@ cat .planning/phases/XX-name/${PHASE}-CONTEXT.md 2>/dev/null **If neither exist:** Suggest /gsd:research-phase for niche domains, /gsd:discuss-phase for simpler domains, or proceed with roadmap only. - -**BEFORE breaking into tasks, work BACKWARD from the phase goal.** - -This step prevents the common failure mode: tasks complete but goal not achieved. - -See `~/.claude/get-shit-done/references/goal-backward.md` for complete guidance. - -**1. State the phase goal:** - -Extract from ROADMAP.md. Reframe if task-shaped: -- Task-shaped: "implement chat system" → Outcome-shaped: "users can chat" -- Task-shaped: "add authentication" → Outcome-shaped: "users can log in securely" - -**2. Derive observable truths:** - -Ask: **"What must be TRUE for this goal to be achieved?"** - -List 3-7 truths from the USER's perspective: -- "User can see existing messages" -- "User can type and send a message" -- "Sent message appears in the list" -- "Messages persist across refresh" - -**Test:** Each truth should be verifiable by a human using the app. If you can't test it by clicking around, it's not observable. - -**3. Derive required artifacts:** - -For each truth, ask: **"What must EXIST for this to be true?"** - -Map truths to concrete files: -``` -"User can see existing messages" requires: - - src/components/Chat.tsx (renders messages) - - src/app/api/chat/route.ts (provides messages) - - prisma/schema.prisma (Message model) -``` - -**Test:** Each artifact should be a specific file path. If you can't point to where it lives, it's too abstract. - -**4. Derive key links (wiring):** - -For each artifact, ask: **"What must be CONNECTED for this to function?"** - -Key links are critical connections: -``` -- Chat.tsx → /api/chat: fetch in useEffect, response mapped to state -- /api/chat GET → database: prisma.message.findMany, result returned -- ChatInput onSubmit → /api/chat POST: fetch call, not just console.log -``` - -**Test:** Wiring is verified by tracing data flow. Does A actually call B? - -**5. Identify highest-risk links:** - -Ask: **"Where is this most likely to break?"** - -These get extra verification attention. Common high-risk links: -- Form submit → API call (often stubbed with console.log) -- API handler → database query (often returns hardcoded data) -- Component → real data (often renders placeholder) - -**6. Document must-haves:** - -Structure for PLAN.md frontmatter: - -```yaml -must_haves: - truths: - - "User can see existing messages" - - "User can send a message" - - "Messages persist across refresh" - artifacts: - - path: "src/components/Chat.tsx" - provides: "Message list rendering" - min_lines: 30 - - path: "src/app/api/chat/route.ts" - provides: "Message CRUD" - exports: ["GET", "POST"] - - path: "prisma/schema.prisma" - provides: "Message model" - contains: "model Message" - key_links: - - from: "src/components/Chat.tsx" - to: "/api/chat" - via: "fetch in useEffect" - pattern: "fetch.*api/chat" - - from: "src/app/api/chat/route.ts" - to: "prisma.message" - via: "database query" - pattern: "prisma\\.message" -``` - -**7. Use must-haves to inform task design:** - -Tasks should CREATE artifacts and ESTABLISH key links. When writing tasks: -- Each artifact should have a task that creates it -- Each key link should be established (not left as TODO) -- Verification should check the link works, not just that files exist - -**Why this matters:** - -Without goal-backward derivation, you get: -- "Create Chat.tsx" ✓ (file exists, but renders placeholder) -- "Create API route" ✓ (file exists, but returns hardcoded data) -- "Phase complete" ✓ (all tasks done) -- "App doesn't work" ✗ (goal not achieved) - -With goal-backward derivation: -- Must-haves define what "working" means -- Tasks are designed to achieve must-haves -- Verification checks must-haves after execution -- Gaps found before they compound into later phases - - Decompose phase into tasks. **Think dependencies first, not sequence.** @@ -843,23 +837,30 @@ Tasks are instructions for Claude, not Jira tickets. -Phase planning complete when: +**Standard mode** — Phase planning complete when: - [ ] STATE.md read, project history absorbed - [ ] Mandatory discovery completed (Level 0-3) - [ ] Prior decisions, issues, concerns synthesized -- [ ] **Must-haves derived** (truths, artifacts, key links from goal-backward analysis) - [ ] Dependency graph built (needs/creates for each task) - [ ] Tasks grouped into plans by wave, not by sequence - [ ] PLAN file(s) exist with XML structure - [ ] Each plan: depends_on, files_modified, autonomous in frontmatter -- [ ] **Each plan: must_haves in frontmatter** (for post-execution verification) - [ ] Each plan: user_setup declared if external services involved - [ ] Each plan: Objective, context, tasks, verification, success criteria, output - [ ] Each plan: 2-3 tasks (~50% context) - [ ] Each task: Type, Files (if auto), Action, Verify, Done -- [ ] **Tasks designed to CREATE artifacts and ESTABLISH key links** - [ ] Checkpoints properly structured - [ ] Wave structure maximizes parallelism - [ ] PLAN file(s) committed to git - [ ] User knows next steps and wave structure + +**Gap closure mode (`--gaps`)** — Planning complete when: +- [ ] VERIFICATION.md loaded and gaps parsed +- [ ] Existing SUMMARYs read for context +- [ ] Gaps clustered into focused plans +- [ ] Plan numbers sequential after existing (04, 05...) +- [ ] PLAN file(s) exist with gap_closure: true +- [ ] Each plan: tasks derived from gap.missing items +- [ ] PLAN file(s) committed to git +- [ ] User knows to run `/gsd:execute-phase {X}` next