systematic-debugging

# Systematic Debugging

## When to Use

Invoke this methodology automatically when:
- A test fails and the cause isn't immediately obvious
- Unexpected behavior occurs in production or development
- An error message doesn't directly point to the fix
- Multiple potential causes exist

## Core Principles

1. **Hypothesize before acting** - Form explicit hypotheses about root cause before changing code
2. **Test hypotheses systematically** - Validate or eliminate each hypothesis with evidence
3. **Parallelize investigation** - Use subagents for concurrent readonly exploration
4. **Preserve test integrity** - Never weaken tests to make them pass

## Debugging Workflow

### Phase 1: Reproduce and Isolate

1. **Reproduce the failure** - Confirm the bug exists and is reproducible
2. **Create a failing unit test** (when practical) - Captures the bug and verifies the fix
   - Not always possible (environment-specific issues, race conditions)
   - Don't spend excessive time if a test isn't natural to write
3. **Gather initial evidence** - Read error messages, logs, stack traces

### Phase 2: Form Hypotheses

Before touching any code, explicitly list potential causes:

```
Hypotheses:
1. [Most likely] The X component isn't handling Y case
2. [Possible] Race condition between A and B
3. [Less likely] Configuration mismatch in Z
```

Rank by likelihood based on evidence. Avoid anchoring on the first idea.

### Phase 3: Investigate Systematically

**For each hypothesis:**
1. Identify what evidence would confirm or refute it
2. Gather that evidence (logs, code reading, adding debug output)
3. Update hypothesis ranking based on findings
4. Move to next hypothesis if current one is eliminated

**Parallel investigation with subagents:**

Use the `codebase-investigator` agent for independent, readonly investigations. Spawn multiple investigators in parallel, each with a specific focus.

```
Spawn investigators in parallel using Task tool:

1. Task tool with subagent_type="codebase-inv