fix(offer-next): remove code blocks from output templates for proper markdown rendering

Commands with <offer_next> sections were outputting backticks literally instead of rendering them as inline code. Removed code block wrappers and added explicit 'Output this markdown directly' instruction. Affected: plan-phase, execute-phase, audit-milestone
2026-01-17 00:01:30 -06:00
parent cfe237d439
commit 8d199427a8
6 changed files with 248 additions and 90 deletions
--- a/commands/gsd/audit-milestone.md
+++ b/commands/gsd/audit-milestone.md
@@ -143,9 +143,12 @@ Route by status (see `<offer_next>`).
 </process>

 <offer_next>
+Output this markdown directly (not as a code block). Route based on status:
+
+---
+
 **If passed:**

-```markdown
 ## ✓ Milestone {version} — Audit Passed

 **Score:** {N}/{M} requirements satisfied
@@ -153,22 +156,22 @@ Route by status (see `<offer_next>`).

 All requirements covered. Cross-phase integration verified. E2E flows complete.

---
+───────────────────────────────────────────────────────────────

 ## ▶ Next Up

 **Complete milestone** — archive and tag

-`/gsd:complete-milestone {version}`
+/gsd:complete-milestone {version}

-<sub>`/clear` first → fresh context window</sub>
-```
+<sub>/clear first → fresh context window</sub>
+
+───────────────────────────────────────────────────────────────

 ---

 **If gaps_found:**

-```markdown
 ## ⚠ Milestone {version} — Gaps Found

 **Score:** {N}/{M} requirements satisfied
@@ -190,28 +193,28 @@ All requirements covered. Cross-phase integration verified. E2E flows complete.
 {For each flow gap:}
 - **{flow name}:** breaks at {step}

---
+───────────────────────────────────────────────────────────────

 ## ▶ Next Up

 **Plan gap closure** — create phases to complete milestone

-`/gsd:plan-milestone-gaps`
+/gsd:plan-milestone-gaps

-<sub>`/clear` first → fresh context window</sub>
+<sub>/clear first → fresh context window</sub>

---
+───────────────────────────────────────────────────────────────

 **Also available:**
- `cat .planning/v{version}-MILESTONE-AUDIT.md` — see full report
- `/gsd:complete-milestone {version}` — proceed anyway (accept tech debt)
-```
+- cat .planning/v{version}-MILESTONE-AUDIT.md — see full report
+- /gsd:complete-milestone {version} — proceed anyway (accept tech debt)
+
+───────────────────────────────────────────────────────────────

 ---

 **If tech_debt (no blockers but accumulated debt):**

-```markdown
 ## ⚡ Milestone {version} — Tech Debt Review

 **Score:** {N}/{M} requirements satisfied
@@ -228,20 +231,21 @@ All requirements met. No critical blockers. Accumulated tech debt needs review.

 ### Total: {N} items across {M} phases

---
+───────────────────────────────────────────────────────────────

 ## ▶ Options

 **A. Complete milestone** — accept debt, track in backlog

-`/gsd:complete-milestone {version}`
+/gsd:complete-milestone {version}

 **B. Plan cleanup phase** — address debt before completing

-`/gsd:plan-milestone-gaps`
+/gsd:plan-milestone-gaps

-<sub>`/clear` first → fresh context window</sub>
-```
+<sub>/clear first → fresh context window</sub>
+
+───────────────────────────────────────────────────────────────
 </offer_next>

 <success_criteria>
--- a/commands/gsd/execute-phase.md
+++ b/commands/gsd/execute-phase.md
@@ -105,9 +105,7 @@ Phase: $ARGUMENTS
 </process>

 <offer_next>
-**MANDATORY: Present copy/paste-ready next command.**
-
-After verification completes, route based on status:
+Output this markdown directly (not as a code block). Route based on status:

 | Status | Route |
 |--------|-------|
@@ -120,7 +118,6 @@ After verification completes, route based on status:

 **Route A: Phase verified, more phases remain**

-```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GSD ► PHASE {Z} COMPLETE ✓
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -136,24 +133,22 @@ Goal verified ✓

 **Phase {Z+1}: {Name}** — {Goal from ROADMAP.md}

-`/gsd:discuss-phase {Z+1}` — gather context and clarify approach
+/gsd:discuss-phase {Z+1} — gather context and clarify approach

-<sub>`/clear` first → fresh context window</sub>
+<sub>/clear first → fresh context window</sub>

 ───────────────────────────────────────────────────────────────

 **Also available:**
- `/gsd:plan-phase {Z+1}` — skip discussion, plan directly
- `/gsd:verify-work {Z}` — manual acceptance testing before continuing
+- /gsd:plan-phase {Z+1} — skip discussion, plan directly
+- /gsd:verify-work {Z} — manual acceptance testing before continuing

 ───────────────────────────────────────────────────────────────
-```

 ---

 **Route B: Phase verified, milestone complete**

-```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GSD ► MILESTONE COMPLETE 🎉
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -169,24 +164,22 @@ All phase goals verified ✓

 **Audit milestone** — verify requirements, cross-phase integration, E2E flows

-`/gsd:audit-milestone`
+/gsd:audit-milestone

-<sub>`/clear` first → fresh context window</sub>
+<sub>/clear first → fresh context window</sub>

 ───────────────────────────────────────────────────────────────

 **Also available:**
- `/gsd:verify-work` — manual acceptance testing
- `/gsd:complete-milestone` — skip audit, archive directly
+- /gsd:verify-work — manual acceptance testing
+- /gsd:complete-milestone — skip audit, archive directly

 ───────────────────────────────────────────────────────────────
-```

 ---

 **Route C: Gaps found — need additional planning**

-```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GSD ► PHASE {Z} GAPS FOUND ⚠
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -194,7 +187,7 @@ All phase goals verified ✓
 **Phase {Z}: {Name}**

 Score: {N}/{M} must-haves verified
-Report: `.planning/phases/{phase_dir}/{phase}-VERIFICATION.md`
+Report: .planning/phases/{phase_dir}/{phase}-VERIFICATION.md

 ### What's Missing

@@ -206,23 +199,24 @@ Report: `.planning/phases/{phase_dir}/{phase}-VERIFICATION.md`

 **Plan gap closure** — create additional plans to complete the phase

-`/gsd:plan-phase {Z} --gaps`
+/gsd:plan-phase {Z} --gaps

-<sub>`/clear` first → fresh context window</sub>
+<sub>/clear first → fresh context window</sub>

 ───────────────────────────────────────────────────────────────

 **Also available:**
- `cat .planning/phases/{phase_dir}/{phase}-VERIFICATION.md` — see full report
- `/gsd:verify-work {Z}` — manual testing before planning
+- 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`:
+---
+
+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
+3. User runs /gsd:execute-phase {Z} again
 4. Execute-phase runs incomplete plans (04, 05...)
 5. Verifier runs again → loop until passed
 </offer_next>
--- a/commands/gsd/plan-phase.md
+++ b/commands/gsd/plan-phase.md
@@ -419,7 +419,13 @@ Wait for user response.

 ## 13. Present Final Status

-```
+Route to `<offer_next>`.
+
+</process>
+
+<offer_next>
+Output this markdown directly (not as a code block):
+
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GSD ► PHASE {X} PLANNED ✓
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -440,20 +446,18 @@ Verification: {Passed | Passed with override | Skipped}

 **Execute Phase {X}** — run all {N} plans

-`/gsd:execute-phase {X}`
+/gsd:execute-phase {X}

-<sub>`/clear` first → fresh context window</sub>
+<sub>/clear first → fresh context window</sub>

 ───────────────────────────────────────────────────────────────

 **Also available:**
- `cat .planning/phases/{phase-dir}/*-PLAN.md` — review plans
- `/gsd:plan-phase {X} --research` — re-research first
+- cat .planning/phases/{phase-dir}/*-PLAN.md — review plans
+- /gsd:plan-phase {X} --research — re-research first

 ───────────────────────────────────────────────────────────────
-```
-
-</process>
+</offer_next>

 <success_criteria>
 - [ ] .planning/ directory validated
--- a/commands/gsd/verify-work.md
+++ b/commands/gsd/verify-work.md
@@ -9,14 +9,15 @@ allowed-tools:
  - Grep
  - Edit
  - Write
+  - Task
 ---

 <objective>
 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.
+Purpose: Confirm what Claude built actually works from user's perspective. One test at a time, plain text responses, no interrogation. When issues are found, automatically diagnose, plan fixes, and prepare for execution.

-Output: {phase}-UAT.md tracking all test results, gaps logged for /gsd:plan-phase --gaps
+Output: {phase}-UAT.md tracking all test results. If issues found: diagnosed gaps, verified fix plans ready for /gsd:execute-phase
 </objective>

 <execution_context>
@@ -43,7 +44,13 @@ Phase: $ARGUMENTS (optional)
   - Wait for plain text response
   - "yes/y/next" = pass, anything else = issue (severity inferred)
 6. Update UAT.md after each response
-7. On completion: commit, present summary, offer next steps
+7. On completion: commit, present summary
+8. If issues found:
+   - Spawn parallel debug agents to diagnose root causes
+   - Spawn gsd-planner in --gaps mode to create fix plans
+   - Spawn gsd-plan-checker to verify fix plans
+   - Iterate planner ↔ checker until plans pass (max 3)
+   - Present ready status with `/clear` then `/gsd:execute-phase`
 </process>

 <anti_patterns>
@@ -51,7 +58,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 as gaps for /gsd:plan-phase --gaps
+- Don't fix issues during testing — log as gaps, diagnose after all tests complete
 </anti_patterns>

 <success_criteria>
@@ -61,5 +68,8 @@ Phase: $ARGUMENTS (optional)
 - [ ] Severity inferred, never asked
 - [ ] Batched writes: on issue, every 5 passes, or completion
 - [ ] Committed on completion
- [ ] Clear next steps based on results
+- [ ] If issues: parallel debug agents diagnose root causes
+- [ ] If issues: gsd-planner creates fix plans from diagnosed gaps
+- [ ] If issues: gsd-plan-checker verifies fix plans (max 3 iterations)
+- [ ] Ready for `/gsd:execute-phase` when complete
 </success_criteria>
--- a/get-shit-done/workflows/diagnose-issues.md
+++ b/get-shit-done/workflows/diagnose-issues.md
@@ -164,10 +164,13 @@ git commit -m "docs({phase}): add root causes from diagnosis"
 </step>

 <step name="report_results">
-**Report diagnosis results:**
+**Report diagnosis results and hand off:**

+Display:
 ```
-## Diagnosis Complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► DIAGNOSIS COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 | Gap (Truth) | Root Cause | Files |
 |-------------|------------|-------|
@@ -175,26 +178,13 @@ git commit -m "docs({phase}): add root causes from diagnosis"
 | 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}/
+Debug sessions: ${DEBUG_DIR}/

---
-
-Next steps:
- `/gsd:plan-phase {phase} --gaps` — Create fix plans from diagnosed gaps
- Review debug sessions for details
+Proceeding to plan fixes...
 ```
-</step>

-<step name="offer_next">
-**Offer gap closure:**
-
-```
-Root causes identified. Ready to plan fixes?
-
-`/gsd:plan-phase {phase} --gaps`
-
-The fix plans will use diagnosed root causes for targeted fixes.
-```
+Return to verify-work orchestrator for automatic planning.
+Do NOT offer manual next steps - verify-work handles the rest.
 </step>

 </process>
@@ -239,5 +229,5 @@ The fix plans will use diagnosed root causes for targeted fixes.
 - [ ] Root causes collected from all agents
 - [ ] UAT.md gaps updated with artifacts and missing
 - [ ] Debug sessions saved to ${DEBUG_DIR}/
- [ ] User knows next steps (plan-phase --gaps)
+- [ ] Hand off to verify-work for automatic planning
 </success_criteria>
--- a/get-shit-done/workflows/verify-work.md
+++ b/get-shit-done/workflows/verify-work.md
@@ -334,28 +334,180 @@ 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_gap_closure`
+- Proceed to `plan_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_gap_closure">
-**Offer next steps after diagnosis:**
+<step name="plan_gap_closure">
+**Auto-plan fixes from diagnosed gaps:**
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► PLANNING FIXES
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Spawning planner for gap closure...
+```
+
+Spawn gsd-planner in --gaps mode:

 ```
---
+Task(
+  prompt="""
+<planning_context>

-## Diagnosis Complete
+**Phase:** {phase_number}
+**Mode:** gap_closure

-| Gap | Root Cause |
-|-----|------------|
-| {truth 1} | {root_cause} |
-| {truth 2} | {root_cause} |
-...
+**UAT with diagnoses:**
+@.planning/phases/{phase_dir}/{phase}-UAT.md

-Next steps:
- `/gsd:plan-phase {phase} --gaps` — Create fix plans from diagnosed gaps
- `/gsd:verify-work {phase}` — Re-test after fixes
+**Project State:**
+@.planning/STATE.md
+
+**Roadmap:**
+@.planning/ROADMAP.md
+
+</planning_context>
+
+<downstream_consumer>
+Output consumed by /gsd:execute-phase
+Plans must be executable prompts.
+</downstream_consumer>
+""",
+  subagent_type="gsd-planner",
+  description="Plan gap fixes for Phase {phase}"
+)
+```
+
+On return:
+- **PLANNING COMPLETE:** Proceed to `verify_gap_plans`
+- **PLANNING INCONCLUSIVE:** Report and offer manual intervention
+</step>
+
+<step name="verify_gap_plans">
+**Verify fix plans with checker:**
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► VERIFYING FIX PLANS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Spawning plan checker...
+```
+
+Initialize: `iteration_count = 1`
+
+Spawn gsd-plan-checker:
+
+```
+Task(
+  prompt="""
+<verification_context>
+
+**Phase:** {phase_number}
+**Phase Goal:** Close diagnosed gaps from UAT
+
+**Plans to verify:**
+@.planning/phases/{phase_dir}/*-PLAN.md
+
+</verification_context>
+
+<expected_output>
+Return one of:
+- ## VERIFICATION PASSED — all checks pass
+- ## ISSUES FOUND — structured issue list
+</expected_output>
+""",
+  subagent_type="gsd-plan-checker",
+  description="Verify Phase {phase} fix plans"
+)
+```
+
+On return:
+- **VERIFICATION PASSED:** Proceed to `present_ready`
+- **ISSUES FOUND:** Proceed to `revision_loop`
+</step>
+
+<step name="revision_loop">
+**Iterate planner ↔ checker until plans pass (max 3):**
+
+**If iteration_count < 3:**
+
+Display: `Sending back to planner for revision... (iteration {N}/3)`
+
+Spawn gsd-planner with revision context:
+
+```
+Task(
+  prompt="""
+<revision_context>
+
+**Phase:** {phase_number}
+**Mode:** revision
+
+**Existing plans:**
+@.planning/phases/{phase_dir}/*-PLAN.md
+
+**Checker issues:**
+{structured_issues_from_checker}
+
+</revision_context>
+
+<instructions>
+Read existing PLAN.md files. Make targeted updates to address checker issues.
+Do NOT replan from scratch unless issues are fundamental.
+</instructions>
+""",
+  subagent_type="gsd-planner",
+  description="Revise Phase {phase} plans"
+)
+```
+
+After planner returns → spawn checker again (verify_gap_plans logic)
+Increment iteration_count
+
+**If iteration_count >= 3:**
+
+Display: `Max iterations reached. {N} issues remain.`
+
+Offer options:
+1. Force proceed (execute despite issues)
+2. Provide guidance (user gives direction, retry)
+3. Abandon (exit, user runs /gsd:plan-phase manually)
+
+Wait for user response.
+</step>
+
+<step name="present_ready">
+**Present completion and next steps:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► FIXES READY ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Phase {X}: {Name}** — {N} gap(s) diagnosed, {M} fix plan(s) created
+
+| Gap | Root Cause | Fix Plan |
+|-----|------------|----------|
+| {truth 1} | {root_cause} | {phase}-04 |
+| {truth 2} | {root_cause} | {phase}-04 |
+
+Plans verified and ready for execution.
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Execute fixes** — run fix plans
+
+`/clear` then `/gsd:execute-phase {phase}`
+
+───────────────────────────────────────────────────────────────
 ```
 </step>

@@ -403,5 +555,9 @@ Default to **major** if unclear. User can correct if needed.
 - [ ] Severity inferred from description (never asked)
 - [ ] Batched writes: on issue, every 5 passes, or completion
 - [ ] Committed on completion
- [ ] Clear next steps based on results (plan-phase --gaps if issues)
+- [ ] If issues: parallel debug agents diagnose root causes
+- [ ] If issues: gsd-planner creates fix plans (gap_closure mode)
+- [ ] If issues: gsd-plan-checker verifies fix plans
+- [ ] If issues: revision loop until plans pass (max 3 iterations)
+- [ ] Ready for `/gsd:execute-phase` when complete
 </success_criteria>