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
This commit is contained in:
Lex Christopherson
2026-01-17 00:01:30 -06:00
parent cfe237d439
commit 8d199427a8
6 changed files with 248 additions and 90 deletions

View File

@@ -143,9 +143,12 @@ Route by status (see `<offer_next>`).
</process> </process>
<offer_next> <offer_next>
Output this markdown directly (not as a code block). Route based on status:
---
**If passed:** **If passed:**
```markdown
## ✓ Milestone {version} — Audit Passed ## ✓ Milestone {version} — Audit Passed
**Score:** {N}/{M} requirements satisfied **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. All requirements covered. Cross-phase integration verified. E2E flows complete.
--- ───────────────────────────────────────────────────────────────
## ▶ Next Up ## ▶ Next Up
**Complete milestone** — archive and tag **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:** **If gaps_found:**
```markdown
## ⚠ Milestone {version} — Gaps Found ## ⚠ Milestone {version} — Gaps Found
**Score:** {N}/{M} requirements satisfied **Score:** {N}/{M} requirements satisfied
@@ -190,28 +193,28 @@ All requirements covered. Cross-phase integration verified. E2E flows complete.
{For each flow gap:} {For each flow gap:}
- **{flow name}:** breaks at {step} - **{flow name}:** breaks at {step}
--- ───────────────────────────────────────────────────────────────
## ▶ Next Up ## ▶ Next Up
**Plan gap closure** — create phases to complete milestone **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:** **Also available:**
- `cat .planning/v{version}-MILESTONE-AUDIT.md` — see full report - cat .planning/v{version}-MILESTONE-AUDIT.md — see full report
- `/gsd:complete-milestone {version}` — proceed anyway (accept tech debt) - /gsd:complete-milestone {version} — proceed anyway (accept tech debt)
```
───────────────────────────────────────────────────────────────
--- ---
**If tech_debt (no blockers but accumulated debt):** **If tech_debt (no blockers but accumulated debt):**
```markdown
## ⚡ Milestone {version} — Tech Debt Review ## ⚡ Milestone {version} — Tech Debt Review
**Score:** {N}/{M} requirements satisfied **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 ### Total: {N} items across {M} phases
--- ───────────────────────────────────────────────────────────────
## ▶ Options ## ▶ Options
**A. Complete milestone** — accept debt, track in backlog **A. Complete milestone** — accept debt, track in backlog
`/gsd:complete-milestone {version}` /gsd:complete-milestone {version}
**B. Plan cleanup phase** — address debt before completing **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> </offer_next>
<success_criteria> <success_criteria>

View File

@@ -105,9 +105,7 @@ Phase: $ARGUMENTS
</process> </process>
<offer_next> <offer_next>
**MANDATORY: Present copy/paste-ready next command.** Output this markdown directly (not as a code block). Route based on status:
After verification completes, route based on status:
| Status | Route | | Status | Route |
|--------|-------| |--------|-------|
@@ -120,7 +118,6 @@ After verification completes, route based on status:
**Route A: Phase verified, more phases remain** **Route A: Phase verified, more phases remain**
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► PHASE {Z} COMPLETE ✓ GSD ► PHASE {Z} COMPLETE ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -136,24 +133,22 @@ Goal verified ✓
**Phase {Z+1}: {Name}** — {Goal from ROADMAP.md} **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:** **Also available:**
- `/gsd:plan-phase {Z+1}` — skip discussion, plan directly - /gsd:plan-phase {Z+1} — skip discussion, plan directly
- `/gsd:verify-work {Z}` — manual acceptance testing before continuing - /gsd:verify-work {Z} — manual acceptance testing before continuing
─────────────────────────────────────────────────────────────── ───────────────────────────────────────────────────────────────
```
--- ---
**Route B: Phase verified, milestone complete** **Route B: Phase verified, milestone complete**
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► MILESTONE COMPLETE 🎉 GSD ► MILESTONE COMPLETE 🎉
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -169,24 +164,22 @@ All phase goals verified ✓
**Audit milestone** — verify requirements, cross-phase integration, E2E flows **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:** **Also available:**
- `/gsd:verify-work` — manual acceptance testing - /gsd:verify-work — manual acceptance testing
- `/gsd:complete-milestone` — skip audit, archive directly - /gsd:complete-milestone — skip audit, archive directly
─────────────────────────────────────────────────────────────── ───────────────────────────────────────────────────────────────
```
--- ---
**Route C: Gaps found — need additional planning** **Route C: Gaps found — need additional planning**
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► PHASE {Z} GAPS FOUND ⚠ GSD ► PHASE {Z} GAPS FOUND ⚠
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -194,7 +187,7 @@ All phase goals verified ✓
**Phase {Z}: {Name}** **Phase {Z}: {Name}**
Score: {N}/{M} must-haves verified 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 ### 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 **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:** **Also available:**
- `cat .planning/phases/{phase_dir}/{phase}-VERIFICATION.md` — see full report - cat .planning/phases/{phase_dir}/{phase}-VERIFICATION.md — see full report
- `/gsd:verify-work {Z}` — manual testing before planning - /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 1. Planner reads VERIFICATION.md gaps
2. Creates plans 04, 05, etc. to close 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...) 4. Execute-phase runs incomplete plans (04, 05...)
5. Verifier runs again → loop until passed 5. Verifier runs again → loop until passed
</offer_next> </offer_next>

View File

@@ -419,7 +419,13 @@ Wait for user response.
## 13. Present Final Status ## 13. Present Final Status
``` Route to `<offer_next>`.
</process>
<offer_next>
Output this markdown directly (not as a code block):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► PHASE {X} PLANNED ✓ GSD ► PHASE {X} PLANNED ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -440,20 +446,18 @@ Verification: {Passed | Passed with override | Skipped}
**Execute Phase {X}** — run all {N} plans **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:** **Also available:**
- `cat .planning/phases/{phase-dir}/*-PLAN.md` — review plans - cat .planning/phases/{phase-dir}/*-PLAN.md — review plans
- `/gsd:plan-phase {X} --research` — re-research first - /gsd:plan-phase {X} --research — re-research first
─────────────────────────────────────────────────────────────── ───────────────────────────────────────────────────────────────
``` </offer_next>
</process>
<success_criteria> <success_criteria>
- [ ] .planning/ directory validated - [ ] .planning/ directory validated

View File

@@ -9,14 +9,15 @@ allowed-tools:
- Grep - Grep
- Edit - Edit
- Write - Write
- Task
--- ---
<objective> <objective>
Validate built features through conversational testing with persistent state. 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> </objective>
<execution_context> <execution_context>
@@ -43,7 +44,13 @@ Phase: $ARGUMENTS (optional)
- Wait for plain text response - Wait for plain text response
- "yes/y/next" = pass, anything else = issue (severity inferred) - "yes/y/next" = pass, anything else = issue (severity inferred)
6. Update UAT.md after each response 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> </process>
<anti_patterns> <anti_patterns>
@@ -51,7 +58,7 @@ Phase: $ARGUMENTS (optional)
- Don't ask severity — infer from description - Don't ask severity — infer from description
- Don't present full checklist upfront — one test at a time - Don't present full checklist upfront — one test at a time
- Don't run automated tests — this is manual user validation - 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> </anti_patterns>
<success_criteria> <success_criteria>
@@ -61,5 +68,8 @@ Phase: $ARGUMENTS (optional)
- [ ] Severity inferred, never asked - [ ] Severity inferred, never asked
- [ ] Batched writes: on issue, every 5 passes, or completion - [ ] Batched writes: on issue, every 5 passes, or completion
- [ ] Committed on 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> </success_criteria>

View File

@@ -164,10 +164,13 @@ git commit -m "docs({phase}): add root causes from diagnosis"
</step> </step>
<step name="report_results"> <step name="report_results">
**Report diagnosis results:** **Report diagnosis results and hand off:**
Display:
``` ```
## Diagnosis Complete ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► DIAGNOSIS COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
| Gap (Truth) | Root Cause | Files | | 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 | | Reply button positioned correctly | CSS flex order incorrect | ReplyButton.tsx |
| Delete removes comment | API missing auth header | api/comments.ts | | Delete removes comment | API missing auth header | api/comments.ts |
Debug sessions saved to ${DEBUG_DIR}/ Debug sessions: ${DEBUG_DIR}/
--- Proceeding to plan fixes...
Next steps:
- `/gsd:plan-phase {phase} --gaps` — Create fix plans from diagnosed gaps
- Review debug sessions for details
``` ```
</step>
<step name="offer_next"> Return to verify-work orchestrator for automatic planning.
**Offer gap closure:** Do NOT offer manual next steps - verify-work handles the rest.
```
Root causes identified. Ready to plan fixes?
`/gsd:plan-phase {phase} --gaps`
The fix plans will use diagnosed root causes for targeted fixes.
```
</step> </step>
</process> </process>
@@ -239,5 +229,5 @@ The fix plans will use diagnosed root causes for targeted fixes.
- [ ] Root causes collected from all agents - [ ] Root causes collected from all agents
- [ ] UAT.md gaps updated with artifacts and missing - [ ] UAT.md gaps updated with artifacts and missing
- [ ] Debug sessions saved to ${DEBUG_DIR}/ - [ ] Debug sessions saved to ${DEBUG_DIR}/
- [ ] User knows next steps (plan-phase --gaps) - [ ] Hand off to verify-work for automatic planning
</success_criteria> </success_criteria>

View File

@@ -334,28 +334,180 @@ Spawning parallel debug agents to investigate each issue.
- Spawn parallel debug agents for each issue - Spawn parallel debug agents for each issue
- Collect root causes - Collect root causes
- Update UAT.md with 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. Diagnosis runs automatically - no user prompt. Parallel agents investigate simultaneously, so overhead is minimal and fixes are more accurate.
</step> </step>
<step name="offer_gap_closure"> <step name="plan_gap_closure">
**Offer next steps after diagnosis:** **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 | **UAT with diagnoses:**
|-----|------------| @.planning/phases/{phase_dir}/{phase}-UAT.md
| {truth 1} | {root_cause} |
| {truth 2} | {root_cause} |
...
Next steps: **Project State:**
- `/gsd:plan-phase {phase} --gaps` — Create fix plans from diagnosed gaps @.planning/STATE.md
- `/gsd:verify-work {phase}` — Re-test after fixes
**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> </step>
@@ -403,5 +555,9 @@ Default to **major** if unclear. User can correct if needed.
- [ ] Severity inferred from description (never asked) - [ ] Severity inferred from description (never asked)
- [ ] Batched writes: on issue, every 5 passes, or completion - [ ] Batched writes: on issue, every 5 passes, or completion
- [ ] Committed on 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> </success_criteria>