From 37adcfbb6b21ee630593a7fe0906ffb0e611456d Mon Sep 17 00:00:00 2001
From: Tibsfox <tibsfox@tibsfox.com>
Date: Wed, 1 Apr 2026 16:08:48 -0700
Subject: [PATCH] feat(debug): add --diagnose flag for diagnosis-only mode
 (#1396)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add --diagnose flag to /gsd:debug that stops after finding the root
cause without applying a fix. Returns a structured Root Cause Report
with confidence level, files involved, and suggested fix strategies.
Offers "Fix now" to spawn a continuation agent, "Plan fix", or
"Manual fix" options.

Recreated cleanly on current main — previous version carried stale
shared fixes that are now upstream.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 commands/gsd/debug.md | 31 ++++++++++++++++++++++---------
 1 file changed, 22 insertions(+), 9 deletions(-)

diff --git a/commands/gsd/debug.md b/commands/gsd/debug.md
index 9a2a728d3..993ac6d23 100644
--- a/commands/gsd/debug.md
+++ b/commands/gsd/debug.md
@@ -1,7 +1,7 @@
 ---
 name: gsd:debug
 description: Systematic debugging with persistent state across context resets
-argument-hint: [issue description]
+argument-hint: [--diagnose] [issue description]
 allowed-tools:
   - Read
   - Bash
@@ -15,6 +15,9 @@ Debug issues using scientific method with subagent isolation.
 **Orchestrator role:** Gather symptoms, spawn gsd-debugger agent, handle checkpoints, spawn continuations.
 
 **Why subagent:** Investigation burns context fast (reading files, forming hypotheses, testing). Fresh 200k context per investigation. Main context stays lean for user interaction.
+
+**Flags:**
+- `--diagnose` — Diagnose only. Find root cause without applying a fix. Returns a structured Root Cause Report. Use when you want to validate the diagnosis before committing to a fix.
 </objective>
 
 <available_agent_types>
@@ -25,6 +28,10 @@ Valid GSD subagent types (use exact names — do not fall back to 'general-purpo
 <context>
 User's issue: $ARGUMENTS
 
+Parse flags from $ARGUMENTS:
+- If `--diagnose` is present, set `diagnose_only=true` and remove the flag from the issue description.
+- Otherwise, `diagnose_only=false`.
+
 Check for active sessions:
 ```bash
 ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
@@ -87,7 +94,7 @@ timeline: {timeline}
 
 <mode>
 symptoms_prefilled: true
-goal: find_and_fix
+goal: {if diagnose_only: "find_root_cause_only", else: "find_and_fix"}
 </mode>
 
 <debug_file>
@@ -106,12 +113,18 @@ Task(
 
 ## 4. Handle Agent Return
 
-**If `## ROOT CAUSE FOUND`:**
-- Display root cause and evidence summary
+**If `## ROOT CAUSE FOUND` (diagnose-only mode):**
+- Display root cause, confidence level, files involved, and suggested fix strategies
 - Offer options:
-  - "Fix now" - spawn fix subagent
-  - "Plan fix" - suggest /gsd:plan-phase --gaps
-  - "Manual fix" - done
+  - "Fix now" — spawn a continuation agent with `goal: find_and_fix` to apply the fix (see step 5)
+  - "Plan fix" — suggest `/gsd:plan-phase --gaps`
+  - "Manual fix" — done
+
+**If `## DEBUG COMPLETE` (find_and_fix mode):**
+- Display root cause and fix summary
+- Offer options:
+  - "Plan fix" — suggest `/gsd:plan-phase --gaps` if further work needed
+  - "Done" — mark resolved
 
 **If `## CHECKPOINT REACHED`:**
 - Present checkpoint details to user
@@ -128,9 +141,9 @@ Task(
   - "Manual investigation" - done
   - "Add more context" - gather more symptoms, spawn again
 
-## 5. Spawn Continuation Agent (After Checkpoint)
+## 5. Spawn Continuation Agent (After Checkpoint or "Fix now")
 
-When user responds to checkpoint, spawn fresh agent:
+When user responds to checkpoint OR selects "Fix now" from diagnose-only results, spawn fresh agent:
 
 ```markdown
 <objective>