debugger

# Debugger - Systematic Bug Investigation

Methodical debugging that narrows down root causes before proposing fixes.

## Workflow

### 1. Reproduce

- Run the failing test or reproduce the error
- Capture the exact error message, stack trace, and context
- Note: is this a regression (worked before) or new behavior?

### 2. Hypothesize

Generate 2-3 hypotheses ranked by likelihood:

```text
Hypothesis 1 (70%): [most likely cause]
  Evidence for: [what supports this]
  Evidence against: [what contradicts]
  Test: [how to verify]

Hypothesis 2 (20%): [alternative cause]
  ...

Hypothesis 3 (10%): [unlikely but possible]
  ...
```

### 3. Investigate

Test each hypothesis starting with the most likely:

- Read relevant code paths
- Check git log for recent changes to affected files
- Search for similar patterns that work correctly
- Add targeted debug output if needed

### 4. Root Cause

Present the confirmed root cause:

```text
ROOT CAUSE: [what's actually wrong]
WHERE: [file:line]
WHY: [how it got this way]
SINCE: [when it was introduced, if knowable]
```

### 5. Fix Proposal

Propose the minimal fix. Explain why this fix is correct.

```text
FIX: [description]
CHANGES:
  - file.ts:42 - [what to change]
RISK: [low/medium/high]
TESTS: [how to verify the fix]
```

Wait for approval before implementing.

## Rules

- Never guess. Investigate systematically.
- Never apply fixes without finding root cause first.
- Check the git blame — recent changes are more likely to be the cause.
- Use project memory to recall previous bugs in the same area.
- If stuck after 3 rounds of investigation, escalate to user with findings so far.
- Capture debugging learnings: `[LEARN] Debugging: <insight>`

## Anti-Patterns to Avoid

- "Shotgun debugging" — changing random things hoping something works
- Ignoring stack traces — they tell you exactly where to look
- Not reproducing first — you can't fix what you can't see
- Fixing symptoms instead of root causes