systematic-debugging git:20260709.887cd3fA

Immutable. This exact content never changes and is served at /api/v1/blob/307a58b3207f8ece.

---
name: systematic-debugging
description: Reduce, observe, reason, predict, probe, then fix — no guessing.
---

# Systematic Debugging Protocol

You are now operating under Dave's debugging protocol. This is not optional guidance — it is the mandatory sequence for investigating any failure. Agents who skip steps reliably produce wrong fixes that waste time and create new bugs.

## The Protocol

Every debug cycle follows this sequence. No skipping steps.

### 1. REDUCE

Before tracing anything, reduce to the **smallest case that still fails**.

- Remove variables one at a time until you find the one that matters
- If a complex test fails, try the simplest version first
- If multiple things are broken, isolate one failure before investigating
- The dimension you add back that triggers the failure is where the bug lives

If the minimal case passes, use **divergence-point analysis**: compare the passing case against the failing case signal-by-signal, log-by-log, output-by-output. The first thing that diverges is closest to root cause.

### 2. OBSERVE

What does the data show? Not what you think should happen — what **actually** happens.

- List specific values, states, outputs at specific points
- Cover ALL relevant signals/variables, not just the one that looks wrong
- Use real data: logs, debugger output, test results, actual error messages
- Do NOT use your mental model as evidence. Your mental model is a hypothesis.
- If comparing two cases, lay them side by side

### 3. REASON

Trace the logic step by step to a **specific mechanism** that explains ALL observed data.

- Follow every variable, every branch, every state transition
- Run the reasoning to its conclusion — not "it might be X" but "the specific mechanism is X because of data points A, B, C"
- If your theory explains some observations but not others, the theory is wrong
- If you can't explain all the data, you haven't reasoned far enough

### 4. PREDICT

State specific, falsifiable predictions:

```
"If [hypothesis], then [specific observable] at [specific point] should be [specific value]"
"If [hypothesis is wrong], then [specific observable] will be [other value]"
```

A prediction you can't check is useless. Every prediction must name something you can actually observe.

### 5. PROBE

Check the prediction against actual data. **This step is mandatory before any fix.**

- Run the test, check the log, inspect the variable, read the output
- Compare actual vs. predicted
- If the probe **confirms** the prediction: proceed to FIX
- If the probe **contradicts** the prediction: the hypothesis is wrong. **Go back to OBSERVE.** Do not patch the hypothesis — start over with the new data.

### 6. FIX

Only after root cause is confirmed by PROBE:

- Apply ONE change that addresses the root cause
- If it doesn't work, **revert before trying the next thing**
- After fixing, verify the original failure is resolved AND no new failures were introduced

## Rules

- **Never apply a fix before confirming root cause with data** (PROBE complete)
- **Never stack multiple changes** — one hypothesis, one run
- **Never theorize without data for more than 2 minutes** — check actual state
- **Never skip PROBE** — a fix based on REASON alone is a guess, no matter how confident you are
- **The output is TRUTH.** Your mental model is a hypothesis.
- **If you catch yourself saying "it should be..."** — stop. Check what it actually is.

## Anti-Patterns

| What goes wrong | What to do instead |
|---|---|
| "Let me just try changing this" | OBSERVE first. What does the data say? |
| Changing 3 things at once | One change. Run. Check. |
| "It must be X" without checking | That's REASON without PROBE. Check. |
| Guessing for 20 minutes | 2 minutes of theory max, then look at actual data |
| Fix didn't work, trying another fix | Revert first. Then re-OBSERVE with new data. |
| "That's weird, let me try..." | Weird = your model is wrong. OBSERVE harder. |