debug

Systematic debugging with persistent state across context resets

Overview

The debug command uses scientific method and subagent isolation to systematically investigate and fix issues. Debug state persists across context resets, allowing deep investigation without burning main context.

Syntax

/gsd:debug [issue-description]

issue-description · string

Brief description of the issue to debug. If omitted, GSD lists active debug sessions to resume.

How It Works

Orchestrator Role (Main Session)

• Gathers symptoms from user
• Spawns gsd-debugger subagents
• Handles checkpoints
• Spawns continuation agents
• Keeps main context lean

Debugger Subagent (Fresh 200k Context)

• Deep file investigation
• Hypothesis formation and testing
• Evidence gathering
• Root cause analysis
• Fix implementation
• Writes to .planning/debug/{slug}.md

Why Subagents?

Investigation burns context fast (reading files, forming hypotheses, testing). Fresh 200k context per investigation allows thorough debugging without clogging main session.

Debug Workflow

1. Symptom Gathering

GSD asks structured questions:

1. Expected behavior - What should happen?
2. Actual behavior - What happens instead?
3. Error messages - Any errors? (paste or describe)
4. Timeline - When did this start? Ever worked?
5. Reproduction - How do you trigger it?

2. Investigation

Debugger agent:

• Reads relevant files
• Forms hypotheses
• Tests assumptions
• Gathers evidence
• Eliminates possibilities
• Identifies root cause

3. Checkpoints

Agent returns to orchestrator when:

• Root cause found → Offers fix options
• Needs user input → Asks for clarification
• Verification needed → User tests the fix
• Context reset needed → Saves state, spawns fresh agent

4. Resolution

Once root cause confirmed:

• Fix now - Spawn fix subagent
• Plan fix - Create phase plan (--gaps mode)
• Manual fix - User handles it

Usage Examples

New debug session

/gsd:debug Users can't log in with Google OAuth

GSD gathers symptoms:

Expected: Users click "Login with Google" and authenticate
Actual: Redirect happens but shows "Invalid state" error
Errors: "OAuth state parameter mismatch"
Timeline: Started after deploying yesterday
Reproduction: Any user, any browser

GSD spawns debugger:

• Investigates OAuth flow
• Checks state parameter handling
• Reviews recent changes
• Finds: State stored in memory, lost on server restart
• Root cause: Missing session persistence

Resume existing session

/gsd:debug

GSD lists active sessions:

 Active Debug Sessions:

1. google-oauth-login-fails
   Status: Root cause found
   Hypothesis: Session state not persisted
   Next: Ready to fix

2. slow-dashboard-queries  
   Status: Investigating
   Hypothesis: Missing index on user_events
   Next: Waiting for EXPLAIN results

Select a number to resume, or describe a new issue:

Debug with checkpoints

/gsd:debug API returns 500 on product search

Investigation process:

Checkpoint 1: Need user verification

Agent: Found potential issue - search query isn't sanitized.
       Can you try: curl -X POST /api/search -d '{"q":"test"}'
       and share the full error?

User: [pastes error with SQL syntax details]

Agent continues with new evidence...

Checkpoint 2: Root cause found

ROOT CAUSE: SQL injection vulnerability
- File: api/search.ts:45
- Query concatenates user input directly
- Missing parameterized query

Options:
1. Fix now (spawn fix agent)
2. Plan fix (create security phase)
3. Manual fix

Debug File Structure

.planning/debug/
├── google-oauth-login-fails.md
├── slow-dashboard-queries.md
└── api-500-product-search.md

Debug File Format

# Debug: google-oauth-login-fails

Created: 2026-03-06 14:30
Status: root_cause_found

## Symptoms
- Expected: OAuth login succeeds
- Actual: "Invalid state" error
- Errors: State parameter mismatch
- Timeline: After deploy 2026-03-05
- Reproduction: All users, all browsers

## Hypotheses Tested
1. ❌ Cookie settings - Cookies working fine
2. ❌ Redirect URL mismatch - URLs correct
3. ✅ Session persistence - State lost on restart

## Evidence
- server.ts:23 - Session uses MemoryStore
- deploy.log - Server restarted 2026-03-05 23:15
- User reports align with restart time

## Root Cause
OAuth state stored in memory-only session store.
Server restart clears all sessions, invalidating
state parameters for in-flight OAuth flows.

## Solution
Switch to persistent session store (Redis).

Checkpoint Types

human-verify

Agent needs user to test something:
- Run a command
- Test a scenario
- Verify behavior
- Check logs

need-input

Agent needs clarification:
- Additional symptoms
- Environment details
- Configuration values
- Access credentials

context-reset

Agent used most of context window:
- Saves state to debug file
- Returns to orchestrator
- Orchestrator spawns fresh agent
- Fresh agent loads state, continues

Debug Modes

find_and_fix (default)

• Investigate root cause
• Propose fix
• Implement fix (if user approves)

investigate_only

• Find root cause
• Document findings
• Don’t implement fix

Status Values

• investigating - Actively gathering evidence
• hypothesis_formed - Testing specific theory
• root_cause_found - Issue identified
• fix_proposed - Solution ready
• fixed - Fix implemented
• verified - User confirmed fixed
• resolved - Session complete

When to Use

Perfect for

• Production issues
• Intermittent bugs
• Performance problems
• Integration failures
• “It worked yesterday” scenarios
• Complex reproduction steps
• Deep investigation needed

Not needed for

• Syntax errors (clear from error message)
• Known bugs with known fixes
• Simple logic errors
• Tasks better suited for /gsd:quick

Integration with Planning

If fix is complex, route to phase planning:

# Debug finds root cause
/gsd:debug

# Fix requires multiple changes
GSD: "This fix needs a dedicated phase. Creating plan..."

# Creates phase with --gaps context
/gsd:plan-phase --gaps

The --gaps flag passes debug findings to planner.

Success Criteria

• ✅ Active sessions checked
• ✅ Symptoms gathered (if new)
• ✅ gsd-debugger spawned with context
• ✅ Checkpoints handled correctly
• ✅ Root cause confirmed before fixing
• ✅ Debug state persisted in file
• ✅ User knows resolution status

Related Commands

• quick - For simple fixes after debugging
• plan-phase - For complex fixes needing full phase
• add-todo - Capture debug findings as todos
• health - Check for orphaned debug sessions