diff --git a/README.md b/README.md index 043313880..b17b43297 100644 --- a/README.md +++ b/README.md @@ -377,7 +377,6 @@ You're never locked in. The system adapts. | Command | What it does | |---------|--------------| | `/gsd:verify-work [N]` | User acceptance test of phase or plan ¹ | -| `/gsd:plan-fix [plan]` | Plan fixes for UAT issues | ### Milestones diff --git a/commands/gsd/debug.md b/commands/gsd/debug.md index 573f7af73..5471f106a 100644 --- a/commands/gsd/debug.md +++ b/commands/gsd/debug.md @@ -96,7 +96,7 @@ Task( - Display root cause and evidence summary - Offer options: - "Fix now" → spawn fix subagent - - "Plan fix" → suggest /gsd:plan-fix + - "Plan fix" → suggest /gsd:plan-phase --gaps - "Manual fix" → done **If `## CHECKPOINT REACHED`:** diff --git a/commands/gsd/plan-fix.md b/commands/gsd/plan-fix.md deleted file mode 100644 index 020c4555c..000000000 --- a/commands/gsd/plan-fix.md +++ /dev/null @@ -1,270 +0,0 @@ ---- -name: gsd:plan-fix -description: Plan fixes for UAT issues from verify-work -argument-hint: "" -allowed-tools: - - Read - - Bash - - Write - - Glob - - Grep - - AskUserQuestion - - SlashCommand ---- - - -Create FIX.md plan from UAT issues found during verify-work. - -Purpose: Plan fixes for issues logged in {phase}-UAT.md. -Output: {phase}-FIX.md in the phase directory, ready for execution. - - - -@~/.claude/get-shit-done/references/plan-format.md -@~/.claude/get-shit-done/references/checkpoints.md - - - -Phase: $ARGUMENTS (required - e.g., "4") - -@.planning/STATE.md -@.planning/ROADMAP.md - - - - - -**Parse phase argument:** - -$ARGUMENTS should be a phase number like "4" or "04". - -If no argument provided: -``` -Error: Phase number required. - -Usage: /gsd:plan-fix 4 - -This creates a fix plan from .planning/phases/04-name/04-UAT.md -``` -Exit. - - - -**Find UAT.md file:** - -```bash -ls .planning/phases/${PHASE_ARG}*/*-UAT.md 2>/dev/null -``` - -If not found: -``` -No UAT.md found for phase {phase}. - -UAT.md files are created by /gsd:verify-work during testing. -Run /gsd:verify-work {phase} first. -``` -Exit. - -If found but status is "testing": -``` -UAT session still in progress. - -Run /gsd:verify-work to complete testing first. -``` -Exit. - - - -**Read issues from UAT.md:** - -Read the "Issues for /gsd:plan-fix" section. - -If section is empty or says "[none yet]": -``` -No issues found in UAT.md. - -All tests passed - no fix plan needed. -``` -Exit. - -Parse each issue: -- ID (UAT-XXX) -- Brief summary -- Severity (blocker/major/minor/cosmetic) -- Test number (for context) -- **root_cause** (if diagnosed - may be empty) - -Also read the corresponding test from "Tests" section to get: -- expected behavior -- reported issue (verbatim user description) -- root_cause (if diagnosed) -- debug_session (path to debug file, if diagnosed) - -**Check if diagnosed:** -- If UAT.md status is "diagnosed" OR root_cause fields are populated → issues have been investigated -- If not diagnosed → plan based on symptoms only (less precise) - - - -**Create fix tasks:** - -For each issue (or logical group): -- Create one task per issue OR -- Group related cosmetic/minor issues into single task - -**If diagnosed (root_cause available):** -```xml - - Fix UAT-{NNN}: {issue summary} - {files from diagnosis} - -**Root Cause:** {root_cause from diagnosis} -**Issue:** {verbatim reported description} -**Expected:** {from test} - -**Fix:** {specific fix based on diagnosed root cause} - -Debug session: {debug_session path} (for reference) - - -- Confirm root cause addressed -- {expected behavior} now works correctly - - UAT-{NNN} resolved - {root_cause} fixed - -``` - -**If NOT diagnosed (symptoms only):** -```xml - - Fix UAT-{NNN}: {issue summary} - [affected files - infer from test context] - -**Issue:** {verbatim reported description} -**Expected:** {from test} - -[Investigate and fix - root cause unknown] - - -- Reproduce original issue - confirm fixed -- {expected behavior} now works correctly - - UAT-{NNN} resolved - {expected behavior} works - -``` - -Prioritize: blocker → major → minor → cosmetic - - - -**Write FIX.md:** - -Create `.planning/phases/XX-name/{phase}-FIX.md`: - -```markdown ---- -phase: XX-name -plan: {phase}-FIX -type: fix -wave: 1 -depends_on: [] -autonomous: true ---- - - -Fix {N} UAT issues from phase {phase}. - -Source: {phase}-UAT.md -Diagnosed: {yes/no - whether root causes were identified} -Priority: {blocker count} blocker, {major count} major, {minor count} minor, {cosmetic count} cosmetic - - - -@~/.claude/get-shit-done/workflows/execute-plan.md -@~/.claude/get-shit-done/templates/summary.md - - - -@.planning/STATE.md -@.planning/ROADMAP.md - -**Issues being fixed:** -@.planning/phases/XX-name/{phase}-UAT.md - -**Debug sessions (if diagnosed):** -[Reference each debug_session path from UAT.md for full investigation context] - -**Original plans for reference:** -@.planning/phases/XX-name/{phase}-01-PLAN.md -[other relevant plans] - - - -[Generated fix tasks] - - - -Before declaring plan complete: -- [ ] All blocker issues fixed -- [ ] All major issues fixed -- [ ] Minor/cosmetic issues fixed or documented as deferred -- [ ] Each fix verified against original reported issue - - - -- All UAT issues from {phase}-UAT.md addressed -- Tests pass -- Ready for re-verification with /gsd:verify-work {phase} - - - -After completion, create `.planning/phases/XX-name/{phase}-FIX-SUMMARY.md` - -``` - - - -**Offer execution:** - -``` -## Fix Plan Created - -**{phase}-FIX.md** — {N} issues to fix - -| Severity | Count | -|----------|-------| -| Blocker | {n} | -| Major | {n} | -| Minor | {n} | -| Cosmetic | {n} | -``` - -Use AskUserQuestion: -- header: "Next" -- question: "What would you like to do?" -- options: - - "Execute fix plan" — Run the fixes now - - "Review plan first" — Look at the plan before executing - - "Done for now" — Come back later - -**If "Execute fix plan":** -Invoke `/gsd:execute-plan .planning/phases/XX-name/{phase}-FIX.md` - -**If "Review plan first":** -Display the plan contents, then ask again whether to execute. - -**If "Done for now":** -``` -Fix plan saved. Run when ready: -`/gsd:execute-plan .planning/phases/XX-name/{phase}-FIX.md` -``` - - - - - -- [ ] UAT.md found and issues parsed -- [ ] Fix tasks created for each issue -- [ ] FIX.md written with proper structure -- [ ] User offered next steps - diff --git a/commands/gsd/progress.md b/commands/gsd/progress.md index ec58b4ff0..f6f9f5777 100644 --- a/commands/gsd/progress.md +++ b/commands/gsd/progress.md @@ -114,28 +114,28 @@ List files in the current phase directory: ```bash ls -1 .planning/phases/[current-phase-dir]/*-PLAN.md 2>/dev/null | wc -l ls -1 .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null | wc -l -ls -1 .planning/phases/[current-phase-dir]/*-ISSUES.md 2>/dev/null | wc -l -ls -1 .planning/phases/[current-phase-dir]/*-FIX.md 2>/dev/null | wc -l -ls -1 .planning/phases/[current-phase-dir]/*-FIX-SUMMARY.md 2>/dev/null | wc -l +ls -1 .planning/phases/[current-phase-dir]/*-UAT.md 2>/dev/null | wc -l ``` -State: "This phase has {X} plans, {Y} summaries, {Z} issues files, {W} fix plans." +State: "This phase has {X} plans, {Y} summaries." -**Step 1.5: Check for unaddressed UAT issues** +**Step 1.5: Check for unaddressed UAT gaps** -For each *-ISSUES.md file, check if matching *-FIX.md exists. -For each *-FIX.md file, check if matching *-FIX-SUMMARY.md exists. +Check for UAT.md files with status "diagnosed" (has gaps needing fixes). + +```bash +# Check for diagnosed UAT with gaps +grep -l "status: diagnosed" .planning/phases/[current-phase-dir]/*-UAT.md 2>/dev/null +``` Track: -- `issues_without_fix`: ISSUES.md files without FIX.md -- `fixes_without_summary`: FIX.md files without FIX-SUMMARY.md +- `uat_with_gaps`: UAT.md files with status "diagnosed" (gaps need fixing) **Step 2: Route based on counts** | Condition | Meaning | Action | |-----------|---------|--------| -| fixes_without_summary > 0 | Unexecuted fix plans exist | Go to **Route A** (with FIX.md) | -| issues_without_fix > 0 | UAT issues need fix plans | Go to **Route E** | +| uat_with_gaps > 0 | UAT gaps need fix plans | Go to **Route E** | | summaries < plans | Unexecuted plans exist | Go to **Route A** | | summaries = plans AND plans > 0 | Phase complete | Go to Step 3 | | plans = 0 | Phase not yet planned | Go to **Route B** | @@ -209,18 +209,18 @@ Check if `{phase}-CONTEXT.md` exists in phase directory. --- -**Route E: UAT issues need fix plans** +**Route E: UAT gaps need fix plans** -ISSUES.md exists without matching FIX.md. User needs to plan fixes. +UAT.md exists with gaps (diagnosed issues). User needs to plan fixes. ``` --- -## ⚠ UAT Issues Found +## ⚠ UAT Gaps Found -**{plan}-ISSUES.md** has {N} issues without a fix plan. +**{phase}-UAT.md** has {N} gaps requiring fixes. -`/gsd:plan-fix {plan}` +`/gsd:plan-phase {phase} --gaps` `/clear` first → fresh context window diff --git a/commands/gsd/verify-work.md b/commands/gsd/verify-work.md index 50810f41d..ad8e25dba 100644 --- a/commands/gsd/verify-work.md +++ b/commands/gsd/verify-work.md @@ -16,7 +16,7 @@ Validate built features through conversational testing with persistent state. Purpose: Confirm what Claude built actually works from user's perspective. One test at a time, plain text responses, no interrogation. -Output: {phase}-UAT.md tracking all test results, issues logged for /gsd:plan-fix +Output: {phase}-UAT.md tracking all test results, gaps logged for /gsd:plan-phase --gaps @@ -51,7 +51,7 @@ Phase: $ARGUMENTS (optional) - Don't ask severity — infer from description - Don't present full checklist upfront — one test at a time - Don't run automated tests — this is manual user validation -- Don't fix issues during testing — log for /gsd:plan-fix +- Don't fix issues during testing — log as gaps for /gsd:plan-phase --gaps diff --git a/get-shit-done/templates/UAT.md b/get-shit-done/templates/UAT.md index e4f82697b..73e6887f5 100644 --- a/get-shit-done/templates/UAT.md +++ b/get-shit-done/templates/UAT.md @@ -39,8 +39,6 @@ expected: [observable behavior] result: issue reported: "[verbatim user response]" severity: major -root_cause: [filled by diagnose-issues, empty until diagnosed] -debug_session: [path to DEBUG file, empty until diagnosed] ### 4. [Test Name] expected: [observable behavior] @@ -57,13 +55,18 @@ issues: [N] pending: [N] skipped: [N] -## Issues for /gsd:plan-fix +## Gaps -- UAT-001: [brief summary] (blocker) - Test 3 - root_cause: [empty until diagnosed] - -- UAT-002: [brief summary] (major) - Test 7 - root_cause: [empty until diagnosed] + +- truth: "[expected behavior from test]" + status: failed + reason: "User reported: [verbatim response]" + severity: blocker | major | minor | cosmetic + test: [N] + root_cause: "" # Filled by diagnosis + artifacts: [] # Filled by diagnosis + missing: [] # Filled by diagnosis + debug_session: "" # Filled by diagnosis ``` --- @@ -87,49 +90,46 @@ skipped: [N] - `result` values: [pending], pass, issue, skipped - If issue: add `reported` (verbatim) and `severity` (inferred) - If skipped: add `reason` if provided -- After diagnosis: add `root_cause` and `debug_session` fields to issues **Summary:** - OVERWRITE counts after each response - Tracks: total, passed, issues, pending, skipped -**Issues for /gsd:plan-fix:** -- APPEND only when issue found -- Format: `- UAT-{NNN}: {summary} ({severity}) - Test {N}` -- After diagnosis: add `root_cause:` line under each issue -- This section feeds directly into /gsd:plan-fix +**Gaps:** +- APPEND only when issue found (YAML format) +- After diagnosis: fill `root_cause`, `artifacts`, `missing`, `debug_session` +- This section feeds directly into /gsd:plan-phase --gaps -**After testing complete (status: complete), if issues exist:** +**After testing complete (status: complete), if gaps exist:** 1. User runs diagnosis (from verify-work offer or manually) 2. diagnose-issues workflow spawns parallel debug agents -3. Each agent investigates one issue, returns root cause -4. UAT.md updated with root causes: - - Each issue test gets `root_cause:` and `debug_session:` fields - - Issues section gets `root_cause:` under each issue +3. Each agent investigates one gap, returns root cause +4. UAT.md Gaps section updated with diagnosis: + - Each gap gets `root_cause`, `artifacts`, `missing`, `debug_session` filled 5. status → "diagnosed" -6. Ready for /gsd:plan-fix with root causes +6. Ready for /gsd:plan-phase --gaps with root causes **After diagnosis:** -```markdown -### 2. Create Top-Level Comment -expected: Submit comment via rich text editor, appears in list with author info -result: issue -reported: "works but doesn't show until I refresh the page" -severity: major -root_cause: useEffect in CommentList.tsx missing commentCount dependency -debug_session: .planning/debug/comment-not-refreshing.md -``` +```yaml +## Gaps -```markdown -## Issues for /gsd:plan-fix - -- UAT-001: Comment doesn't appear until refresh (major) - Test 2 - root_cause: useEffect in CommentList.tsx missing commentCount dependency +- truth: "Comment appears immediately after submission" + status: failed + reason: "User reported: works but doesn't show until I refresh the page" + severity: major + test: 2 + root_cause: "useEffect in CommentList.tsx missing commentCount dependency" + artifacts: + - path: "src/components/CommentList.tsx" + issue: "useEffect missing dependency" + missing: + - "Add commentCount to useEffect dependency array" + debug_session: ".planning/debug/comment-not-refreshing.md" ``` @@ -147,7 +147,7 @@ debug_session: .planning/debug/comment-not-refreshing.md - User responds with pass confirmation or issue description - Update test result (pass/issue/skipped) - Update Summary counts -- If issue: append to Issues section, infer severity +- If issue: append to Gaps section (YAML format), infer severity - Move Current Test to next pending test **On completion:** @@ -182,7 +182,7 @@ Default: **major** (safe default, user can clarify if wrong) ```markdown --- -status: testing +status: diagnosed phase: 04-comments source: 04-01-SUMMARY.md, 04-02-SUMMARY.md started: 2025-01-15T10:30:00Z @@ -191,13 +191,7 @@ updated: 2025-01-15T10:45:00Z ## Current Test -number: 4 -name: Visual Nesting -expected: | - Create 3+ level deep thread. - Each level shows increased indentation with left border. - Nesting caps at reasonable depth. -awaiting: user response +[testing complete] ## Tests @@ -210,8 +204,6 @@ expected: Submit comment via rich text editor, appears in list with author info result: issue reported: "works but doesn't show until I refresh the page" severity: major -root_cause: useEffect in CommentList.tsx missing commentCount dependency -debug_session: .planning/debug/comment-not-refreshing.md ### 3. Reply to a Comment expected: Click Reply, inline composer appears, submit shows nested reply @@ -219,27 +211,37 @@ result: pass ### 4. Visual Nesting expected: 3+ level thread shows indentation, left borders, caps at reasonable depth -result: [pending] +result: pass ### 5. Delete Own Comment expected: Click delete on own comment, removed or shows [deleted] if has replies -result: [pending] +result: pass ### 6. Comment Count expected: Post shows accurate count, increments when adding comment -result: [pending] +result: pass ## Summary total: 6 -passed: 2 +passed: 5 issues: 1 -pending: 3 +pending: 0 skipped: 0 -## Issues for /gsd:plan-fix +## Gaps -- UAT-001: Comment doesn't appear until refresh (major) - Test 2 - root_cause: useEffect in CommentList.tsx missing commentCount dependency +- truth: "Comment appears immediately after submission in list" + status: failed + reason: "User reported: works but doesn't show until I refresh the page" + severity: major + test: 2 + root_cause: "useEffect in CommentList.tsx missing commentCount dependency" + artifacts: + - path: "src/components/CommentList.tsx" + issue: "useEffect missing dependency" + missing: + - "Add commentCount to useEffect dependency array" + debug_session: ".planning/debug/comment-not-refreshing.md" ``` diff --git a/get-shit-done/templates/debug-subagent-prompt.md b/get-shit-done/templates/debug-subagent-prompt.md index 6b0895517..6a46a2c8d 100644 --- a/get-shit-done/templates/debug-subagent-prompt.md +++ b/get-shit-done/templates/debug-subagent-prompt.md @@ -46,7 +46,7 @@ Start directly at investigation_loop. **goal: {goal}** -- `find_root_cause_only` — Diagnose but do NOT fix. Return root cause to orchestrator. Used by UAT diagnosis flow where plan-fix handles the fix. +- `find_root_cause_only` — Diagnose but do NOT fix. Return root cause to orchestrator. Used by UAT diagnosis flow where plan-phase --gaps handles the fix. - `find_and_fix` — Find root cause, then fix and verify. Used by interactive /gsd:debug where user wants immediate resolution. @@ -167,7 +167,7 @@ If you cannot proceed without user action or verification: - [file1]: [what's wrong] - [file2]: [related issue] -**Suggested Fix Direction:** [brief hint for plan-fix, not implementation] +**Suggested Fix Direction:** [brief hint for gap closure plan, not implementation] ``` --- diff --git a/get-shit-done/workflows/debug.md b/get-shit-done/workflows/debug.md index 729bdd6d4..79ce20576 100644 --- a/get-shit-done/workflows/debug.md +++ b/get-shit-done/workflows/debug.md @@ -213,7 +213,7 @@ Reply with A or B (or describe alternative) - Diagnose but don't fix - Stop after confirming root cause - Skip `fix_and_verify` step -- Return root cause to caller (for plan-fix to handle) +- Return root cause to caller (for plan-phase --gaps to handle) **Default mode (no flags):** - Interactive debugging with user @@ -544,7 +544,7 @@ If unable to determine root cause after thorough investigation: **Debug Session:** {path to debug file} ``` -**Do NOT proceed to fix_and_verify.** The fix will be planned by /gsd:plan-fix using this diagnosis. +**Do NOT proceed to fix_and_verify.** The fix will be planned by /gsd:plan-phase --gaps using this diagnosis. diff --git a/get-shit-done/workflows/diagnose-issues.md b/get-shit-done/workflows/diagnose-issues.md index 3bff02bdd..c5bfe0f63 100644 --- a/get-shit-done/workflows/diagnose-issues.md +++ b/get-shit-done/workflows/diagnose-issues.md @@ -1,9 +1,9 @@ -Orchestrate parallel debug agents to investigate UAT issues and find root causes. +Orchestrate parallel debug agents to investigate UAT gaps and find root causes. -After UAT finds issues, spawn one debug agent per issue. Each agent investigates autonomously with symptoms pre-filled from UAT. Collect root causes, update UAT.md, then hand off to plan-fix with actual diagnoses. +After UAT finds gaps, spawn one debug agent per gap. Each agent investigates autonomously with symptoms pre-filled from UAT. Collect root causes, update UAT.md gaps with diagnosis, then hand off to plan-phase --gaps with actual diagnoses. -Orchestrator stays lean: parse issues, spawn agents, collect results, update UAT. +Orchestrator stays lean: parse gaps, spawn agents, collect results, update UAT. @@ -15,7 +15,7 @@ Debug files use the `.planning/debug/` path (hidden directory with leading dot). **Diagnose before planning fixes.** -UAT tells us WHAT is broken (symptoms). Debug agents find WHY (root cause). Plan-fix then creates targeted fixes based on actual causes, not guesses. +UAT tells us WHAT is broken (symptoms). Debug agents find WHY (root cause). plan-phase --gaps then creates targeted fixes based on actual causes, not guesses. Without diagnosis: "Comment doesn't refresh" → guess at fix → maybe wrong With diagnosis: "Comment doesn't refresh" → "useEffect missing dependency" → precise fix @@ -23,26 +23,27 @@ With diagnosis: "Comment doesn't refresh" → "useEffect missing dependency" → - -**Extract issues from UAT.md:** + +**Extract gaps from UAT.md:** -Read the "Issues for /gsd:plan-fix" section: -``` -- UAT-001: Comment doesn't appear until refresh (major) - Test 2 -- UAT-002: Reply button position wrong (minor) - Test 5 -- UAT-003: Delete doesn't work (blocker) - Test 6 +Read the "Gaps" section (YAML format): +```yaml +- truth: "Comment appears immediately after submission" + status: failed + reason: "User reported: works but doesn't show until I refresh the page" + severity: major + test: 2 + artifacts: [] + missing: [] ``` -For each issue, also read the corresponding test from "Tests" section to get: -- expected: What should happen -- reported: What user described (verbatim) -- severity: blocker/major/minor/cosmetic +For each gap, also read the corresponding test from "Tests" section to get full context. -Build issue list: +Build gap list: ``` -issues = [ - {id: "UAT-001", summary: "Comment doesn't appear until refresh", severity: "major", test_num: 2, expected: "...", reported: "..."}, - {id: "UAT-002", summary: "Reply button position wrong", severity: "minor", test_num: 5, expected: "...", reported: "..."}, +gaps = [ + {truth: "Comment appears immediately...", severity: "major", test_num: 2, reason: "..."}, + {truth: "Reply button positioned correctly...", severity: "minor", test_num: 5, reason: "..."}, ... ] ``` @@ -52,50 +53,49 @@ issues = [ **Report diagnosis plan to user:** ``` -## Diagnosing {N} Issues +## Diagnosing {N} Gaps Spawning parallel debug agents to investigate root causes: -| Issue | Summary | Severity | -|-------|---------|----------| -| UAT-001 | Comment doesn't appear until refresh | major | -| UAT-002 | Reply button position wrong | minor | -| UAT-003 | Delete doesn't work | blocker | +| Gap (Truth) | Severity | +|-------------|----------| +| Comment appears immediately after submission | major | +| Reply button positioned correctly | minor | +| Delete removes comment | blocker | Each agent will: -1. Create DEBUG-UAT-{NNN}.md with symptoms pre-filled +1. Create DEBUG-{slug}.md with symptoms pre-filled 2. Investigate autonomously (read code, form hypotheses, test) 3. Return root cause -This runs in parallel - all issues investigated simultaneously. +This runs in parallel - all gaps investigated simultaneously. ``` **Spawn debug agents in parallel:** -For each issue, fill the debug-subagent-prompt template and spawn: +For each gap, fill the debug-subagent-prompt template and spawn: ``` Task( prompt=filled_debug_subagent_prompt, subagent_type="general-purpose", - description="Debug UAT-{NNN}" + description="Debug: {truth_short}" ) ``` **All agents spawn in single message** (parallel execution). Template placeholders: -- `{issue_id}`: UAT-001, UAT-002, etc. -- `{issue_summary}`: Brief description +- `{truth}`: The expected behavior that failed - `{expected}`: From UAT test -- `{actual}`: Verbatim user description (what actually happened) +- `{actual}`: Verbatim user description from reason field - `{errors}`: Any error messages from UAT (or "None reported") - `{reproduction}`: "Test {test_num} in UAT" - `{timeline}`: "Discovered during UAT" -- `{goal}`: `find_root_cause_only` (UAT flow - plan-fix handles fixes) -- `{slug}`: Generated from issue_summary +- `{goal}`: `find_root_cause_only` (UAT flow - plan-phase --gaps handles fixes) +- `{slug}`: Generated from truth @@ -118,14 +118,14 @@ Each agent returns with: - {file1}: {what's wrong} - {file2}: {related issue} -**Suggested Fix Direction:** {brief hint for plan-fix} +**Suggested Fix Direction:** {brief hint for plan-phase --gaps} ``` Parse each return to extract: - root_cause: The diagnosed cause - files: Files involved - debug_path: Path to debug session file -- suggested_fix: Hint for plan-fix +- suggested_fix: Hint for gap closure plan If agent returns `## INVESTIGATION INCONCLUSIVE`: - root_cause: "Investigation inconclusive - manual review needed" @@ -134,34 +134,27 @@ If agent returns `## INVESTIGATION INCONCLUSIVE`: -**Update UAT.md with root causes:** +**Update UAT.md gaps with diagnosis:** -For each issue in the Tests section, add root_cause field: +For each gap in the Gaps section, add artifacts and missing fields: -```markdown -### 2. Create Top-Level Comment -expected: Submit comment via rich text editor, appears in list with author info -result: issue -reported: "works but doesn't show until I refresh the page" -severity: major -root_cause: "useEffect in CommentList.tsx missing commentCount dependency - doesn't re-render when new comment added" -debug_session: ${DEBUG_DIR}/comment-not-refreshing.md +```yaml +- truth: "Comment appears immediately after submission" + status: failed + reason: "User reported: works but doesn't show until I refresh the page" + severity: major + test: 2 + root_cause: "useEffect in CommentList.tsx missing commentCount dependency" + artifacts: + - path: "src/components/CommentList.tsx" + issue: "useEffect missing dependency" + missing: + - "Add commentCount to useEffect dependency array" + - "Trigger re-render when new comment added" + debug_session: .planning/debug/comment-not-refreshing.md ``` -Update the "Issues for /gsd:plan-fix" section with root causes: - -```markdown -## Issues for /gsd:plan-fix - -- UAT-001: Comment doesn't appear until refresh (major) - Test 2 - root_cause: useEffect missing dependency in CommentList.tsx - -- UAT-002: Reply button position wrong (minor) - Test 5 - root_cause: CSS flex order incorrect in ReplyButton.tsx - -- UAT-003: Delete doesn't work (blocker) - Test 6 - root_cause: API endpoint returns 403 - missing auth header -``` +Update status in frontmatter to "diagnosed". Commit the updated UAT.md: ```bash @@ -176,31 +169,31 @@ git commit -m "docs({phase}): add root causes from diagnosis" ``` ## Diagnosis Complete -| Issue | Root Cause | Files | -|-------|------------|-------| -| UAT-001 | useEffect missing dependency | CommentList.tsx | -| UAT-002 | CSS flex order incorrect | ReplyButton.tsx | -| UAT-003 | API missing auth header | api/comments.ts | +| Gap (Truth) | Root Cause | Files | +|-------------|------------|-------| +| Comment appears immediately | useEffect missing dependency | CommentList.tsx | +| Reply button positioned correctly | CSS flex order incorrect | ReplyButton.tsx | +| Delete removes comment | API missing auth header | api/comments.ts | Debug sessions saved to ${DEBUG_DIR}/ --- Next steps: -- `/gsd:plan-fix {phase}` — Create fix plan with root causes +- `/gsd:plan-phase {phase} --gaps` — Create fix plans from diagnosed gaps - Review debug sessions for details ``` -**Offer plan-fix:** +**Offer gap closure:** ``` Root causes identified. Ready to plan fixes? -`/gsd:plan-fix {phase}` +`/gsd:plan-phase {phase} --gaps` -The fix plan will use diagnosed root causes for targeted fixes. +The fix plans will use diagnosed root causes for targeted fixes. ``` @@ -208,7 +201,7 @@ The fix plan will use diagnosed root causes for targeted fixes. **Orchestrator context:** ~15% -- Parse UAT.md issues +- Parse UAT.md gaps - Fill template strings - Spawn parallel Task calls - Collect results @@ -221,30 +214,30 @@ The fix plan will use diagnosed root causes for targeted fixes. - Returns root cause **No symptom gathering.** Agents start with symptoms pre-filled from UAT. -**No fix application.** Agents only diagnose - plan-fix handles fixes. +**No fix application.** Agents only diagnose - plan-phase --gaps handles fixes. **Agent fails to find root cause:** -- Mark issue as "needs manual review" -- Continue with other issues +- Mark gap as "needs manual review" +- Continue with other gaps - Report incomplete diagnosis **Agent times out:** -- Check DEBUG-UAT-{NNN}.md for partial progress +- Check DEBUG-{slug}.md for partial progress - Can resume with /gsd:debug **All agents fail:** - Something systemic (permissions, git, etc.) - Report for manual investigation -- Fall back to plan-fix without root causes +- Fall back to plan-phase --gaps without root causes (less precise) -- [ ] Issues parsed from UAT.md +- [ ] Gaps parsed from UAT.md - [ ] Debug agents spawned in parallel - [ ] Root causes collected from all agents -- [ ] UAT.md updated with root causes +- [ ] UAT.md gaps updated with artifacts and missing - [ ] Debug sessions saved to ${DEBUG_DIR}/ -- [ ] User knows next steps (plan-fix) +- [ ] User knows next steps (plan-phase --gaps) diff --git a/get-shit-done/workflows/plan-phase.md b/get-shit-done/workflows/plan-phase.md index d1cf8eedd..12eb60cd2 100644 --- a/get-shit-done/workflows/plan-phase.md +++ b/get-shit-done/workflows/plan-phase.md @@ -102,18 +102,29 @@ If `--gaps` present in arguments, switch to gap_closure_mode (see ` -**Triggered by `--gaps` flag.** Plans address verification gaps. +**Triggered by `--gaps` flag.** Plans address verification gaps OR UAT gaps. -**1. Load VERIFICATION.md:** +**1. Find gap sources:** ```bash PHASE_DIR=$(ls -d .planning/phases/${PHASE_ARG}* 2>/dev/null | head -1) -cat "$PHASE_DIR"/*-VERIFICATION.md + +# Check for VERIFICATION.md (code verification gaps) +ls "$PHASE_DIR"/*-VERIFICATION.md 2>/dev/null + +# Check for UAT.md with diagnosed status (user testing gaps) +grep -l "status: diagnosed" "$PHASE_DIR"/*-UAT.md 2>/dev/null ``` -**2. Parse gaps from YAML frontmatter:** +**Priority:** If both exist, load both and combine gaps. UAT gaps (user-discovered) may overlap with verification gaps (code-discovered). -Extract `gaps:` array. Each gap has: +**2. Parse gaps:** + +**From VERIFICATION.md** (if exists): Parse `gaps:` from YAML frontmatter. + +**From UAT.md** (if exists with status: diagnosed): Parse gaps from `## Gaps` section (YAML format). + +Each gap has: - `truth`: The observable behavior that failed - `reason`: Why it failed - `artifacts`: Files with issues diff --git a/get-shit-done/workflows/verify-work.md b/get-shit-done/workflows/verify-work.md index 0c487833b..9cd118e18 100644 --- a/get-shit-done/workflows/verify-work.md +++ b/get-shit-done/workflows/verify-work.md @@ -1,5 +1,5 @@ -Validate built features through conversational testing with persistent state. Creates UAT.md that tracks test progress, survives /clear, and feeds into /gsd:plan-fix. +Validate built features through conversational testing with persistent state. Creates UAT.md that tracks test progress, survives /clear, and feeds gaps into /gsd:plan-phase --gaps. User tests, Claude records. One test at a time. Plain text responses. @@ -153,7 +153,7 @@ issues: 0 pending: [N] skipped: 0 -## Issues for /gsd:plan-fix +## Gaps [none yet] ``` @@ -224,9 +224,15 @@ reported: "{verbatim user response}" severity: {inferred} ``` -Append to Issues section: -``` -- UAT-{NNN}: {brief summary from response} ({severity}) - Test {N} +Append to Gaps section (structured YAML for plan-phase --gaps): +```yaml +- truth: "{expected behavior from test}" + status: failed + reason: "User reported: {verbatim user response}" + severity: {inferred} + test: {N} + artifacts: [] # Filled by diagnosis + missing: [] # Filled by diagnosis ``` **After any response:** @@ -321,12 +327,12 @@ Spawning parallel debug agents to investigate each issue. - Spawn parallel debug agents for each issue - Collect root causes - Update UAT.md with root causes -- Proceed to `offer_plan_fix` +- Proceed to `offer_gap_closure` Diagnosis runs automatically - no user prompt. Parallel agents investigate simultaneously, so overhead is minimal and fixes are more accurate. - + **Offer next steps after diagnosis:** ``` @@ -334,14 +340,14 @@ Diagnosis runs automatically - no user prompt. Parallel agents investigate simul ## Diagnosis Complete -| Issue | Root Cause | -|-------|------------| -| UAT-001 | {root_cause} | -| UAT-002 | {root_cause} | +| Gap | Root Cause | +|-----|------------| +| {truth 1} | {root_cause} | +| {truth 2} | {root_cause} | ... Next steps: -- `/gsd:plan-fix {phase}` — Create fix plan with root causes +- `/gsd:plan-phase {phase} --gaps` — Create fix plans from diagnosed gaps - `/gsd:verify-work {phase}` — Re-test after fixes ``` @@ -349,18 +355,23 @@ Next steps: -**Section update rules:** +**Batched writes for efficiency:** -| Section | Rule | When | -|---------|------|------| +Keep results in memory. Write to file only when: +1. **Issue found** — Preserve the problem immediately +2. **Session complete** — Final write before commit +3. **Checkpoint** — Every 5 passed tests (safety net) + +| Section | Rule | When Written | +|---------|------|--------------| | Frontmatter.status | OVERWRITE | Start, complete | -| Frontmatter.updated | OVERWRITE | Every update | -| Current Test | OVERWRITE | Each test transition | -| Tests.{N}.result | OVERWRITE | When user responds | -| Summary | OVERWRITE | After each response | -| Issues | APPEND | When issue found | +| Frontmatter.updated | OVERWRITE | On any file write | +| Current Test | OVERWRITE | On any file write | +| Tests.{N}.result | OVERWRITE | On any file write | +| Summary | OVERWRITE | On any file write | +| Gaps | APPEND | When issue found | -**Update file AFTER processing each response.** If context resets, file shows exactly where to resume. +On context reset: File shows last checkpoint. Resume from there. @@ -383,8 +394,7 @@ Default to **major** if unclear. User can correct if needed. - [ ] Tests presented one at a time with expected behavior - [ ] User responses processed as pass/issue/skip - [ ] Severity inferred from description (never asked) -- [ ] File updated after each response -- [ ] Can resume perfectly from any /clear +- [ ] Batched writes: on issue, every 5 passes, or completion - [ ] Committed on completion -- [ ] Clear next steps based on results +- [ ] Clear next steps based on results (plan-phase --gaps if issues)