# /grid:debug - Systematic Bug Investigation

---
name: grid:debug
description: Start or resume a hypothesis-driven debug session
argument-hint: "[bug description | session-id]"
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - Task
  - AskUserQuestion
---

Systematic bug investigation using hypothesis-driven debugging. Sessions persist across `/clear`.

## USAGE

`/grid:debug "description of bug"`  — Start new debug session
`/grid:debug`                       — Resume most recent session
`/grid:debug {session-id}`          — Resume specific session

## BEHAVIOR

### New Session (with description)

1. Create session file at `.grid/debug/{timestamp}-{slug}.md`
2. Spawn Debugger program to investigate:

```python
Task(
  prompt=f"""
First, read ~/.claude/agents/grid-debugger.md for your role.

NEW DEBUG SESSION
Session: {session_id}

<symptoms>
{user_description}
</symptoms>

Begin investigation:
1. Create debug file with IMMUTABLE symptoms
2. Form first hypothesis
3. Test hypothesis
4. Report progress to Master Control
""",
  subagent_type="general-purpose",
  model="sonnet",
  description="Debug: {slug}"
)
```

### Resume Session (no args or with session-id)

1. Find session file in `.grid/debug/`
2. Load existing state
3. Spawn Debugger to continue:

```python
Task(
  prompt=f"""
First, read ~/.claude/agents/grid-debugger.md for your role.

RESUME DEBUG SESSION
Session: {session_id}

<session_state>
{session_file_contents}
</session_state>

Continue from where you left off. Do NOT re-test eliminated hypotheses.
""",
  subagent_type="general-purpose",
  model="sonnet",
  description="Resume debug: {slug}"
)
```

## SESSION FILE STRUCTURE

```
.grid/
└── debug/
    ├── 20240123-143000-login-crash.md
    ├── 20240123-160000-api-timeout.md
    └── 20240124-091500-data-loss.md
```

## OUTPUT FORMAT

### Starting New Session

```
DEBUG SESSION
═════════════

Session: 20240123-143000-login-crash
File: .grid/debug/20240123-143000-login-crash.md

Symptoms recorded. Spawning Debugger...

    ╱╲
   ╱  ╲
  ╱ ⚡ ╲
 ╱══════╲
   ↑ Debugger deployed...

Investigating: "App crashes on login"
```

### Resuming Session

```
DEBUG SESSION RESUME
════════════════════

Session: 20240123-143000-login-crash
Status: investigating
Hypotheses tested: 3
Current hypothesis: Token expiry comparison uses string

Loading context and resuming...
```

### Session Complete

```
DEBUG SESSION COMPLETE
══════════════════════

Session: 20240123-143000-login-crash
Status: resolved

Root Cause:
Token `expiresAt` compared as string instead of Date object

Fix Applied:
Commit abc1234: fix(auth): use Date comparison for token expiry

Session file archived at:
.grid/debug/20240123-143000-login-crash.md

End of Line.
```

## FINDING SESSIONS

To list all debug sessions:
```bash
ls -la .grid/debug/
```

Session files contain full investigation history including:
- Immutable symptoms
- All tested hypotheses
- Evidence log
- Resolution (if found)

## CONSTRAINTS

- Sessions are APPEND-ONLY (never delete evidence)
- Symptoms section is IMMUTABLE after creation
- One hypothesis tested at a time
- Tests must be specific and falsifiable

End of Line.