gsd-opencode 1.3.33 → 1.4.2

package/get-shit-done/workflows/complete-milestone.md

@@ -575,7 +575,7 @@ Tag: v[X.Y]
 
 `/gsd:discuss-milestone`
 
-<sub>`/clear` first → fresh context window</sub>
+*`/clear` first → fresh context window*
 
 ---
 

package/get-shit-done/workflows/create-milestone.md

@@ -368,7 +368,7 @@ Milestone v[X.Y] [Name] created:
 
 `/gsd:plan-phase [N]`
 
-<sub>`/clear` first → fresh context window</sub>
+*`/clear` first → fresh context window*
 
 ---
 

package/get-shit-done/workflows/create-roadmap.md

@@ -271,7 +271,7 @@ Proceed directly to create_structure step.
 </if>
 
 <if mode="interactive" OR="missing OR custom with gates.confirm_roadmap true">
-Use AskUserQuestion:
+Use question:
 
 - header: "Ready"
 - question: "Ready to create the roadmap, or would you like me to ask more questions?"
@@ -432,7 +432,7 @@ Project initialized:
 
 `/gsd:plan-phase 1`
 
-<sub>`/clear` first → fresh context window</sub>
+*`/clear` first → fresh context window*
 
 ---
 

package/get-shit-done/workflows/debug.md

@@ -0,0 +1,426 @@
+<purpose>
+Systematic debugging with persistent state that survives context resets. The debug file IS the debugging brain - create it immediately and update it continuously.
+
+You are the debugger. The user knows what's wrong (behavior), not why (root cause). Gather symptoms, then investigate autonomously.
+</purpose>
+
+<philosophy>
+**User = reporter. Claude = investigator.**
+
+The user knows:
+- What they expected to happen
+- What actually happened
+- Any error messages they saw
+- When it started / if it ever worked
+
+The user does NOT know (and shouldn't be asked):
+- What's causing the bug
+- Which file has the problem
+- What the fix should be
+
+Ask about experience. Investigate the cause yourself.
+</philosophy>
+
+<references>
+@~/.config/opencode/get-shit-done/references/debugging/debugging-mindset.md
+@~/.config/opencode/get-shit-done/references/debugging/hypothesis-testing.md
+@~/.config/opencode/get-shit-done/references/debugging/investigation-techniques.md
+@~/.config/opencode/get-shit-done/references/debugging/verification-patterns.md
+@~/.config/opencode/get-shit-done/references/debugging/when-to-research.md
+</references>
+
+<template>
+@~/.config/opencode/get-shit-done/templates/DEBUG.md
+</template>
+
+<process>
+
+<step name="check_active_session">
+**First: Check for active debug sessions**
+
+```bash
+ls .planning/debug/*.md 2>/dev/null | grep -v resolved
+```
+
+**If active sessions exist AND no $ARGUMENTS provided:**
+
+Read each file's frontmatter (status, trigger) and Current Focus (hypothesis, next_action).
+
+Display inline:
+
+```
+## Active Debug Sessions
+
+| # | Slug | Status | Hypothesis | Next Action |
+|---|------|--------|------------|-------------|
+| 1 | auth-logout | investigating | Token refresh not called | Check console output |
+| 2 | api-timeout | gathering | - | Gather symptoms |
+| 3 | cart-bug | fixing | Null reference in context | Apply fix |
+
+Reply with a number to resume, or describe a new issue to start fresh.
+```
+
+Wait for user response.
+
+- If user replies with number (1, 2, 3) → Load that file, go to `resume_from_file`
+- If user replies with text → Treat as new issue trigger, go to `create_debug_file`
+
+**If active sessions exist AND $ARGUMENTS provided:**
+
+User wants to start a new debug session. Continue to `create_debug_file`.
+
+**If no active sessions AND no $ARGUMENTS:**
+
+```
+No active debug sessions.
+
+Describe the issue to start debugging.
+```
+
+Wait for user to describe the issue, then use their response as the trigger.
+
+**If no active sessions AND $ARGUMENTS provided:**
+
+Continue to `create_debug_file` with $ARGUMENTS as trigger.
+</step>
+
+<step name="create_debug_file">
+**Create debug file IMMEDIATELY**
+
+Generate slug from user input (lowercase, hyphens, max 30 chars).
+
+```bash
+mkdir -p .planning/debug
+```
+
+Create file with initial state:
+
+```markdown
+---
+status: gathering
+trigger: "[verbatim $ARGUMENTS]"
+created: [ISO timestamp]
+updated: [ISO timestamp]
+---
+
+## Current Focus
+
+hypothesis: none yet
+test: none
+expecting: none
+next_action: gather symptoms from user
+
+## Symptoms
+
+expected:
+actual:
+errors:
+reproduction:
+started:
+
+## Eliminated
+
+[none yet]
+
+## Evidence
+
+[none yet]
+
+## Resolution
+
+root_cause:
+fix:
+verification:
+files_changed: []
+```
+
+Write to `.planning/debug/[slug].md`
+
+Now proceed to `symptom_gathering`.
+</step>
+
+<step name="symptom_gathering">
+**Gather symptoms through questioning - update file after EACH answer**
+
+CRITICAL: Update the debug file after each piece of information gathered.
+
+**1. Expected behavior:**
+
+Use question:
+- header: "Expected"
+- question: "What should happen?"
+- options: Contextual interpretations + "Let me describe"
+
+After answer → Update Symptoms.expected in debug file
+
+**2. Actual behavior:**
+
+Use question:
+- header: "Actual"
+- question: "What actually happens instead?"
+- options: Common failure modes + "Let me describe"
+
+After answer → Update Symptoms.actual in debug file
+
+**3. Error messages:**
+
+Use question:
+- header: "Errors"
+- question: "Any error messages?"
+- options:
+  - "Yes, I'll paste them"
+  - "Yes, but I don't have them handy"
+  - "No errors - fails silently"
+  - "Not sure"
+
+After answer → Update Symptoms.errors in debug file
+
+**4. When it started:**
+
+Use question:
+- header: "Timeline"
+- question: "When did this start?"
+- options:
+  - "Never worked"
+  - "After a change"
+  - "Intermittent"
+  - "Not sure"
+
+After answer → Update Symptoms.started in debug file
+
+**5. Reproduction:**
+
+Use question:
+- header: "Reproduce"
+- question: "How do you trigger this?"
+- options:
+  - "Specific steps" - I can describe them
+  - "Random" - Happens unpredictably
+  - "Always" - Every time I try
+  - "Not sure"
+
+After answer → Update Symptoms.reproduction in debug file
+
+**6. Ready check:**
+
+Use question:
+- header: "Ready?"
+- question: "Enough context to investigate?"
+- options:
+  - "Start investigating"
+  - "I have more context"
+
+If "I have more context" → receive it, update relevant field, ask again
+If "Start investigating" → Update status to "investigating", proceed to `investigation_loop`
+</step>
+
+<step name="investigation_loop">
+**Autonomous investigation - update file continuously**
+
+CRITICAL: Before EVERY action, update Current Focus. After EVERY finding, append to Evidence.
+
+**Phase 1: Initial evidence gathering**
+
+Update Current Focus:
+```
+hypothesis: gathering initial evidence
+test: examining error context and relevant code
+expecting: clues about failure point
+next_action: [specific next action]
+```
+
+1. If errors exist in Symptoms → search codebase for error text
+2. Identify relevant code area from symptoms
+3. Read relevant files COMPLETELY
+4. Run app/tests to observe behavior firsthand
+
+After EACH finding → Append to Evidence:
+```
+- timestamp: [now]
+  checked: [what]
+  found: [what]
+  implication: [what this means]
+```
+
+**Phase 2: Form hypothesis**
+
+Based on evidence, form SPECIFIC, FALSIFIABLE hypothesis.
+
+Update Current Focus:
+```
+hypothesis: [specific theory]
+test: [how you'll test it]
+expecting: [what proves/disproves it]
+next_action: [immediate next step]
+```
+
+**Phase 3: Test hypothesis**
+
+Execute the test. ONE hypothesis at a time.
+
+Append result to Evidence.
+
+**Phase 4: Evaluate**
+
+If CONFIRMED:
+- Update Resolution.root_cause with evidence
+- Update status to "fixing"
+- Proceed to `fix_and_verify`
+
+If ELIMINATED:
+- Append to Eliminated section:
+  ```
+  - hypothesis: [what was wrong]
+    evidence: [what disproved it]
+    timestamp: [now]
+  ```
+- Form new hypothesis based on evidence
+- Return to Phase 2
+
+**Context management:**
+
+After significant investigation (5+ evidence entries), check if context is heavy.
+If so, ensure Current Focus is fully updated and suggest:
+"Context filling up. Safe to /clear - run /gsd:debug to resume."
+</step>
+
+<step name="resume_from_file">
+**Resume investigation from debug file**
+
+Read the full debug file.
+
+Announce:
+```
+Resuming: [slug]
+Status: [status]
+Current hypothesis: [from Current Focus]
+Evidence gathered: [count]
+Eliminated: [count] hypotheses
+
+Continuing from: [next_action]
+```
+
+Based on status:
+- "gathering" → Continue `symptom_gathering` from where left off
+- "investigating" → Continue `investigation_loop` from Current Focus
+- "fixing" → Continue `fix_and_verify`
+- "verifying" → Continue verification
+
+The file tells you exactly where you were.
+</step>
+
+<step name="fix_and_verify">
+**Apply fix and verify**
+
+Update status to "fixing".
+
+**1. Implement minimal fix**
+
+Update Current Focus:
+```
+hypothesis: [confirmed root cause]
+test: applying fix
+expecting: symptoms resolved
+next_action: implement fix in [files]
+```
+
+Make the SMALLEST change that addresses root cause.
+
+Update Resolution.fix with what was changed and why.
+Update Resolution.files_changed with modified files.
+
+**2. Verify**
+
+Update status to "verifying".
+
+Update Current Focus:
+```
+hypothesis: fix resolves issue
+test: reproducing original symptoms
+expecting: symptoms no longer occur
+next_action: verify fix
+```
+
+Test against original Symptoms:
+- Does expected behavior now occur?
+- Are errors gone?
+- Does reproduction no longer trigger issue?
+
+If verification FAILS:
+- Append finding to Evidence
+- Update status back to "investigating"
+- Root cause was wrong or incomplete
+- Return to `investigation_loop`
+
+If verification PASSES:
+- Update Resolution.verification with how verified
+- Proceed to `archive_session`
+</step>
+
+<step name="archive_session">
+**Archive resolved debug session**
+
+Update status to "resolved".
+
+```bash
+mkdir -p .planning/debug/resolved
+mv .planning/debug/[slug].md .planning/debug/resolved/
+```
+
+Commit:
+```bash
+git add -A
+git commit -m "fix: [brief description from Resolution.fix]
+
+Root cause: [from Resolution.root_cause]
+Debug session: .planning/debug/resolved/[slug].md"
+```
+
+Report:
+```
+Debug complete.
+
+Root cause: [root_cause]
+Fix: [fix]
+Files: [files_changed]
+
+Session archived: .planning/debug/resolved/[slug].md
+```
+
+Use question:
+- header: "Next"
+- question: "What now?"
+- options:
+  - "Continue working" - Back to /gsd:progress
+  - "Test more" - Verify related functionality
+  - "Done" - End session
+</step>
+
+</process>
+
+<update_rules>
+**Section update rules (from template):**
+
+| Section | Rule | When |
+|---------|------|------|
+| Frontmatter.status | OVERWRITE | Each phase transition |
+| Frontmatter.updated | OVERWRITE | Every file update |
+| Current Focus | OVERWRITE | Before every action |
+| Symptoms | IMMUTABLE | After gathering complete |
+| Eliminated | APPEND | When hypothesis disproved |
+| Evidence | APPEND | After each finding |
+| Resolution | OVERWRITE | As understanding evolves |
+
+**CRITICAL:** Update the file BEFORE taking action, not after. If context resets mid-action, the file shows what was about to happen.
+</update_rules>
+
+<success_criteria>
+- [ ] Debug file created IMMEDIATELY on command
+- [ ] File updated after EACH piece of information
+- [ ] Current Focus always reflects NOW
+- [ ] Evidence appended for every finding
+- [ ] Eliminated prevents re-investigation
+- [ ] Can resume perfectly from any /clear
+- [ ] Root cause confirmed with evidence before fixing
+- [ ] Fix verified against original symptoms
+</success_criteria>

package/get-shit-done/workflows/discovery-phase.md

@@ -218,7 +218,7 @@ Write `.planning/phases/XX-name/DISCOVERY.md`:
 After creating DISCOVERY.md, check confidence level.
 
 If confidence is LOW:
-Use AskUserQuestion:
+Use question:
 
 - header: "Low Confidence"
 - question: "Discovery confidence is LOW: [reason]. How would you like to proceed?"

package/get-shit-done/workflows/discuss-milestone.md

@@ -49,7 +49,7 @@ Continue to intake_gate.
 </step>
 
 <step name="intake_gate">
-**CRITICAL: ALL questions use AskUserQuestion. Never ask inline text questions.**
+**CRITICAL: ALL questions use question. Never ask inline text questions.**
 
 The primary question is: **What do you want to build/add/fix?**
 
@@ -62,14 +62,14 @@ Check for inputs:
 
 **1. Open:**
 
-Use AskUserQuestion:
+Use question:
 - header: "Next"
 - question: "What do you want to add, improve, or fix in this milestone?"
 - options: [Deferred issues from STATE.md if any] + ["New features", "Improvements to existing", "Bug fixes", "Let me describe"]
 
 **2. Explore features:**
 
-Based on their response, use AskUserQuestion:
+Based on their response, use question:
 
 If they named specific features:
 - header: "Feature Details"
@@ -88,7 +88,7 @@ If they're not sure:
 
 **3. Prioritize:**
 
-Use AskUserQuestion:
+Use question:
 - header: "Priority"
 - question: "Which of these matters most?"
 - options: [Features they mentioned + "All equally important" + "Let me prioritize"]
@@ -109,7 +109,7 @@ Based on what you described:
 
 **4. Decision gate:**
 
-Use AskUserQuestion:
+Use question:
 - header: "Ready?"
 - question: "Ready to create the milestone, or explore more?"
 - options (ALL THREE REQUIRED):
@@ -216,7 +216,7 @@ Context saved to `.planning/MILESTONE-CONTEXT.md`
 
 `/gsd:new-milestone`
 
-<sub>`/clear` first → fresh context window</sub>
+*`/clear` first → fresh context window*
 
 ---
 ```

package/get-shit-done/workflows/discuss-phase.md

@@ -88,9 +88,9 @@ Continue to questioning.
 </step>
 
 <step name="questioning">
-**CRITICAL: ALL questions use AskUserQuestion. Never ask inline text questions.**
+**CRITICAL: ALL questions use question. Never ask inline text questions.**
 
-Present initial context from roadmap, then immediately use AskUserQuestion:
+Present initial context from roadmap, then immediately use question:
 
 ```
 Phase ${PHASE}: ${PHASE_NAME}
@@ -100,35 +100,28 @@ From the roadmap: ${PHASE_DESCRIPTION}
 
 **1. Open:**
 
-Use AskUserQuestion:
+Use question:
 - header: "Vision"
 - question: "How do you imagine this working?"
 - options: 2-3 interpretations based on the phase description + "Let me describe it"
 
 **2. Follow the thread:**
 
-Based on their response, use AskUserQuestion:
+Based on their response, use question:
 - header: "[Topic they mentioned]"
 - question: "You mentioned [X] — what would that look like?"
 - options: 2-3 interpretations + "Something else"
 
 **3. Sharpen the core:**
 
-Use AskUserQuestion:
+Use question:
 - header: "Essential"
 - question: "What's the most important part of this phase?"
 - options: Key aspects they've mentioned + "All equally important" + "Something else"
 
-**4. Find boundaries:**
+**4. Capture specifics (optional):**
 
-Use AskUserQuestion:
-- header: "Scope"
-- question: "What's explicitly out of scope for this phase?"
-- options: Things that might be tempting + "Nothing specific" + "Let me list them"
-
-**5. Capture specifics (optional):**
-
-If they seem to have specific ideas, use AskUserQuestion:
+If they seem to have specific ideas, use question:
 - header: "Specifics"
 - question: "Any particular look/feel/behavior in mind?"
 - options: Contextual options based on what they've said + "No specifics" + "Let me describe"
@@ -138,10 +131,11 @@ CRITICAL — What NOT to ask:
 - Codebase patterns (you read the code)
 - Success metrics (too corporate)
 - Constraints they didn't mention (don't interrogate)
+- What's out of scope (implicit from roadmap)
 
-**6. Decision gate:**
+**5. Decision gate:**
 
-Use AskUserQuestion:
+Use question:
 - header: "Ready?"
 - question: "Ready to capture this context, or explore more?"
 - options (ALL THREE REQUIRED):
@@ -170,7 +164,6 @@ Populate template sections with VISION context (not technical analysis):
 
 - `<vision>`: How the user imagines this working
 - `<essential>`: What must be nailed in this phase
-- `<boundaries>`: What's explicitly out of scope
 - `<specifics>`: Any particular look/feel/behavior mentioned
 - `<notes>`: Any other context gathered
 
@@ -191,9 +184,6 @@ Created: .planning/phases/${PHASE}-${SLUG}/${PHASE}-CONTEXT.md
 ## Essential
 [What must be nailed]
 
-## Boundaries
-[What's out of scope]
-
 ---
 
 ## ▶ Next Up
@@ -202,7 +192,7 @@ Created: .planning/phases/${PHASE}-${SLUG}/${PHASE}-CONTEXT.md
 
 `/gsd:plan-phase ${PHASE}`
 
-<sub>`/clear` first → fresh context window</sub>
+*`/clear` first → fresh context window*
 
 ---
 
@@ -240,7 +230,7 @@ Confirm: "Committed: docs(${PHASE}): capture phase context"
 
 - Phase validated against roadmap
 - Vision gathered through collaborative thinking (not interrogation)
-- User's imagination captured: how it works, what's essential, what's out of scope
+- User's imagination captured: how it works, what's essential
 - CONTEXT.md created in phase directory
 - CONTEXT.md committed to git
 - User knows next steps (typically: research or plan the phase)