refactor(verify-work): consolidate plan-fix into plan-phase --gaps
Unify gap handling - whether discovered by code verification or user testing, gaps feed into the same plan-phase --gaps workflow. Changes: - Delete commands/gsd/plan-fix.md (redundant) - Update verify-work to route to plan-phase --gaps - Update progress Route E to detect UAT gaps - Change UAT.md "Issues" section to "Gaps" with YAML format - Extend plan-phase --gaps to read from both VERIFICATION.md and UAT.md - Update diagnose-issues to output gaps in YAML format - Update all references (debug, templates, workflows) One path: gap discovered → diagnosed → plan-phase --gaps → fixed Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
@@ -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`:**
|
||||
|
||||
@@ -1,270 +0,0 @@
|
||||
---
|
||||
name: gsd:plan-fix
|
||||
description: Plan fixes for UAT issues from verify-work
|
||||
argument-hint: "<phase, e.g., '4'>"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Bash
|
||||
- Write
|
||||
- Glob
|
||||
- Grep
|
||||
- AskUserQuestion
|
||||
- SlashCommand
|
||||
---
|
||||
|
||||
<objective>
|
||||
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.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/get-shit-done/references/plan-format.md
|
||||
@~/.claude/get-shit-done/references/checkpoints.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
Phase: $ARGUMENTS (required - e.g., "4")
|
||||
|
||||
@.planning/STATE.md
|
||||
@.planning/ROADMAP.md
|
||||
</context>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="parse">
|
||||
**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.
|
||||
</step>
|
||||
|
||||
<step name="find">
|
||||
**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.
|
||||
</step>
|
||||
|
||||
<step name="read">
|
||||
**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)
|
||||
</step>
|
||||
|
||||
<step name="plan">
|
||||
**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
|
||||
<task type="auto">
|
||||
<name>Fix UAT-{NNN}: {issue summary}</name>
|
||||
<files>{files from diagnosis}</files>
|
||||
<action>
|
||||
**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)
|
||||
</action>
|
||||
<verify>
|
||||
- Confirm root cause addressed
|
||||
- {expected behavior} now works correctly
|
||||
</verify>
|
||||
<done>UAT-{NNN} resolved - {root_cause} fixed</done>
|
||||
</task>
|
||||
```
|
||||
|
||||
**If NOT diagnosed (symptoms only):**
|
||||
```xml
|
||||
<task type="auto">
|
||||
<name>Fix UAT-{NNN}: {issue summary}</name>
|
||||
<files>[affected files - infer from test context]</files>
|
||||
<action>
|
||||
**Issue:** {verbatim reported description}
|
||||
**Expected:** {from test}
|
||||
|
||||
[Investigate and fix - root cause unknown]
|
||||
</action>
|
||||
<verify>
|
||||
- Reproduce original issue - confirm fixed
|
||||
- {expected behavior} now works correctly
|
||||
</verify>
|
||||
<done>UAT-{NNN} resolved - {expected behavior} works</done>
|
||||
</task>
|
||||
```
|
||||
|
||||
Prioritize: blocker → major → minor → cosmetic
|
||||
</step>
|
||||
|
||||
<step name="write">
|
||||
**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
|
||||
---
|
||||
|
||||
<objective>
|
||||
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
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/get-shit-done/workflows/execute-plan.md
|
||||
@~/.claude/get-shit-done/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.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]
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
[Generated fix tasks]
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
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
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- All UAT issues from {phase}-UAT.md addressed
|
||||
- Tests pass
|
||||
- Ready for re-verification with /gsd:verify-work {phase}
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/XX-name/{phase}-FIX-SUMMARY.md`
|
||||
</output>
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="offer">
|
||||
**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`
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] UAT.md found and issues parsed
|
||||
- [ ] Fix tasks created for each issue
|
||||
- [ ] FIX.md written with proper structure
|
||||
- [ ] User offered next steps
|
||||
</success_criteria>
|
||||
@@ -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`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
|
||||
@@ -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
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@@ -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
|
||||
</anti_patterns>
|
||||
|
||||
<success_criteria>
|
||||
|
||||
Reference in New Issue
Block a user