debug

Files (1)

• SKILL.md

SKILL.md (first lines)

# Debug

> Relies on BDK foundation (STARTUP_INSTRUCTIONS.md) for project context.

Diagnose bugs via structured investigation, reproduce with failing tests, then fix or plan.

**Announce at start:** "Using debug to investigate the issue."

**Core principle**: Understand first → test second → confirm with user → fix third.

**Run the phases strictly in order. Announce each one as you enter it** (`[debug] Phase 2: Investigate`), and do not enter the next phase until the current one is fully done:

- Phase 1: Parse Input
- Phase 2: Investigate
- Phase 3: Write Failing Tests
- Phase 4: Propose & Wait for User Decision ← **HARD STOP**

Phase 4 is a hard stop: you present the proposal, then end your turn. Do not begin Phase 5, do not start editing, and do not decide the path yourself — no matter how obvious the fix looks. Only an actual user reply releases the stop; a background task completing, a hook firing, or your own reasoning does not.

**After the user responds**: announce Phase 5 as the path they chose — "Fix Inline" or "Hand off to /bdk:create-plan" — then proceed.

---

## Decision Flow

```dot
digraph debug_flow {
    rankdir=TB
    node [shape=box, style="rounded,filled", fillcolor="#f0f0f0"]

    start [label="Phase 1\nParse Input", fillcolor="#d4edda"]
    investigate [label="Phase 2\nInvestigate"]
    tests [label="Phase 3\nWrite Failing Tests"]
    decide [label="Phase 4\nPropose & ASK USER\n(HARD STOP)", fillcolor="#fff3cd", shape=octagon]
    fix [label="Phase 5a\nFix Inline + Verify"]
    plan [label="Phase 5b\nHand off to /bdk:create-plan"]
    done [label="Done", fillcolor="#d4edda", shape=doublecircle]

    start -> investigate
    investigate -> tests
    tests -> decide
    decide -> fix [label="user: 'Fix now'"]
    decide -> plan [label="user: 'Create plan'"]
    decide -> investigate [label="user: 'Something else'"]
    fix -> done
    plan -> done
}
```

---

## The 5-Phase Workflow

### Phase 1: Parse Input

1. **Validate input**: If empty or vague, ask inline for details, then **stop**
2. **Extract key signals**: error type, failing component, steps to reproduce, expected vs actual
3. **Print summary**:
   ```
   [debug] Issue: {one-line summary}
   [debug] Signals: error={exception class or "none"}, component={file/class or "unknown"}
   ```

**GATE**: Must have enough signal to start investigation.

---

### Phase 2: Investigate

1. **Find entry point** — locate the error component or symbol
2. **Trace callers** — trace up the call chain
3. **Trace callees** — trace down to dependencies
4. **Identify impacted paths** — named execution paths through the suspected area
5. **Flag cascading risk** — highest-risk choke points in the affected module
6. **Identify root cause**
7. **Quantify blast radius** — understand scope before proposing fix: find every reference to the symbols you will change, in source and in tests
8. **Scan for related test gaps** — same class of problem in nearby code only
9. **Print investigation summary**:
   ```
   [debug] Root cause: {one sentence}
   [debug] Affected: {file path}:{line range}
   [debug] Test gaps found: {N}
   ```

**GATE**: Must identify root cause before Phase 3.

---

### Phase 3: Write Failing Tests

Write tests that precisely reproduce bug. Tests RED until fix applied.

**Rules:**
- Each test concrete: specific input values, specific expected outcome
- Follow project test conventions (check existing tests for patterns)
- Place tests in correct existing test file

Inject test command: !`python3 ${CLAUDE_PLUGIN_ROOT}/scripts/get_settings.py test-tools`

Confirm the new tests are RED by running the matching tier's `scoped` form on the test file(s) you just wrote, **directly via `Bash`** — substitute `{files}` with those paths. No agent spawn: one test file's output is a few lines, and the spawn costs more wall-clock than the run. Never the `full` form of any tier, and never an e2e tier unless the tests you wrote *are* e2e specs.

```
[debug] Failing tests confirmed: {N} red
```

**GATE**: All new tests must be RED before proceeding.

---

### Phase 4: Propose Solution & Ask User (HARD STOP)

**Mandatory checkpoint. STOP and wait for user decision.**

**Step 1**: Describe proposed solution (what changes, why it fixes root cause, risks)

**Step 2**: Assess complexity:
- **LOW** (inline fix): isolated change affecting one function/call site
- **HIGH** (route to /bdk:create-plan): affects many call sites, introduces new abstractions, changes shared data models

From broneq/bdk, MIT.

More from broneq/bdk