debug

Files (1)

• SKILL.md

SKILL.md (first lines)

<objective>
Debug issues using scientific method with subagent isolation.

**Orchestrator role:** Gather symptoms, spawn bm-debugger agent, handle checkpoints, spawn continuations.

**Why subagent:** Investigation burns context fast. Fresh 200k context per investigation keeps main context 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.

**Subcommands:**
- `list` — List all active debug sessions
- `status <slug>` — Print full summary of a session without spawning an agent
- `continue <slug>` — Resume a specific session by slug
</objective>

<available_agent_types>
Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
- bm-debug-session-manager — manages debug checkpoint/continuation loop in isolated context
- bm-debugger — investigates bugs using scientific method
</available_agent_types>

<context>
User's input: $ARGUMENTS

Parse subcommands and flags from $ARGUMENTS BEFORE the active-session check:
- If $ARGUMENTS starts with "list": SUBCMD=list, no further args
- If $ARGUMENTS starts with "status ": SUBCMD=status, SLUG=remainder (trim whitespace)
- If $ARGUMENTS starts with "continue ": SUBCMD=continue, SLUG=remainder (trim whitespace)
- If $ARGUMENTS contains `--diagnose`: SUBCMD=debug, diagnose_only=true, strip `--diagnose` from description
- Otherwise: SUBCMD=debug, diagnose_only=false

Check for active sessions (used for non-list/status/continue flows):
```bash
ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
```
</context>

<process>

## 0. Initialize Context

```bash
INIT=$(bm-sdk query state.load)
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
```

Extract `commit_docs` from init JSON. Resolve debugger model:
```bash
debugger_model=$(bm-sdk query resolve-model bm-debugger 2>/dev/null | jq -r '.model' 2>/dev/null || true)
```

Read TDD mode from config:
```bash
TDD_MODE=$(bm-sdk query config-get tdd_mode 2>/dev/null | jq -r 'if type == "boolean" then tostring else . end' 2>/dev/null || echo "false")
```

## 1a. LIST subcommand

When SUBCMD=list:

```bash
ls .planning/debug/*.md 2>/dev/null | grep -v resolved
```

For each file found, parse frontmatter fields (`status`, `trigger`, `updated`) and the `Current Focus` block (`hypothesis`, `next_action`). Display a formatted table:

```
Active Debug Sessions
  #  Slug                    Status         Updated
  1  auth-token-null         investigating  2026-04-12
     hypothesis: JWT decode fails when token contains nested claims
     next: Add logging at jwt.verify() call site
Run `/bm:debug continue <slug>` to resume a session.
No sessions? `/bm:debug <description>` to start.
```

If no files exist or the glob returns nothing: print "No active debug sessions. Run `/bm:debug <issue description>` to start one."

STOP after displaying list. Do NOT proceed to further steps.

## 1b. STATUS subcommand

When SUBCMD=status and SLUG is set:

Check `.planning/debug/{SLUG}.md` exists. If not, check `.planning/debug/resolved/{SLUG}.md`. If neither, print "No debug session found with slug: {SLUG}" and stop.

Parse and print full summary:
- Frontmatter (status, trigger, created, updated)
- Current Focus block (all fields including hypothesis, test, expecting, next_action, reasoning_checkpoint if populated, tdd_checkpoint if populated)
- Count of Evidence entries (lines starting with `- timestamp:` in Evidence section)
- Count of Eliminated entries (lines starting with `- hypothesis:` in Eliminated section)
- Resolution fields (root_cause, fix, verification, files_changed — if any populated)
- TDD checkpoint status (if present)
- Reasoning checkpoint fields (if present)

No agent spawn. Just information display. STOP after printing.

## 1c. CONTINUE subcommand

When SUBCMD=continue and SLUG is set:

Check `.planning/debug/{SLUG}.md` exists. If not, print "No active debug session found with slug: {SLUG}. Check `/bm:debug list` for active sessions." and stop.

Read file and print Current Focus block to console:

```
Resuming: {SLUG}
Status: {status}
Hypothesis: {hypothesis}
Next action: {next_action}
Evidence entries: {count}
Eliminated: {count}
```

Surface to user. Then delegate directly to the session manager (skip Steps 2 and 3 — pass `symptoms_prefilled: true` and set the slug from SLUG variable). The existing file IS the context.

Print before spawning:
```

From buildomator/buildomator, MIT.

More from buildomator/buildomator