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
2026-01-15 15:38:21 -06:00
parent 8c66a7167a
commit 2869fee206
11 changed files with 199 additions and 454 deletions

View File

@@ -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.
</step>
<step name="fix_and_verify">

View File

@@ -1,9 +1,9 @@
<purpose>
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.
</purpose>
<paths>
@@ -15,7 +15,7 @@ Debug files use the `.planning/debug/` path (hidden directory with leading dot).
<core_principle>
**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" →
<process>
<step name="parse_issues">
**Extract issues from UAT.md:**
<step name="parse_gaps">
**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.
```
</step>
<step name="spawn_agents">
**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
</step>
<step name="collect_results">
@@ -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`:
</step>
<step name="update_uat">
**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
```
</step>
<step name="offer_next">
**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.
```
</step>
@@ -208,7 +201,7 @@ The fix plan will use diagnosed root causes for targeted fixes.
<context_efficiency>
**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.
</context_efficiency>
<failure_handling>
**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)
</failure_handling>
<success_criteria>
- [ ] 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)
</success_criteria>

View File

@@ -102,18 +102,29 @@ If `--gaps` present in arguments, switch to gap_closure_mode (see `<step name="g
</step>
<step name="gap_closure_mode">
**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

View File

@@ -1,5 +1,5 @@
<purpose>
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.
</purpose>
@@ -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.
</step>
<step name="offer_plan_fix">
<step name="offer_gap_closure">
**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
```
</step>
@@ -349,18 +355,23 @@ Next steps:
</process>
<update_rules>
**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.
</update_rules>
<severity_inference>
@@ -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)
</success_criteria>