Debug

---
name: lore:debug
description: Systematic root-cause debugging with a hard circuit breaker. Use when a bug resists fixing, a test keeps failing, a teammate is stuck after repeated fix attempts, or you catch yourself guessing at fixes instead of finding the cause.
---

# Debug

The building discipline is `/lore:tdd`. This is its diagnostic counterpart: a phased
process for finding the **root cause** of a bug instead of guessing at fixes,
plus a hard circuit breaker that stops a doomed fix loop before it wastes a
whole session.

The failure mode this skill exists to prevent: patching the **symptom** you can
see (the red test, the stack trace, the wrong number) without ever locating the
**fault** that produced it — so the bug moves, reappears, or splits into two.

## Phased process

Work the phases in order. Do not skip ahead to a fix; a fix you can't explain is
a guess, and guesses are what the circuit breaker below exists to catch.

### 1. Reproduce

Get a reliable, minimal reproduction first. A bug you cannot trigger on demand,
you cannot prove you fixed — you can only convince yourself. Shrink it: the
smallest input, the fewest steps, the tightest test that still shows the fault.
A minimal reproduction is often already half the diagnosis.

### 2. Observe

Read the actual evidence before theorizing — the real error message, the full
stack trace, the failing assertion, the logs, the diff since it last worked. Do
not skim the first line and pattern-match. Separate the **symptom** (what you
observe) from the candidate **fault** (what is actually wrong); they are rarely
the same line.

### 3. Hypothesize

Form ONE falsifiable hypothesis about the root cause, and state what must be true
if it holds. "The timestamp is UTC but compared as local" is a hypothesis you can
test; "something's wrong with the dates" is not. One hypothesis at a time — a
scattershot of simultaneous guesses is how the attempt counter below runs out.

### 4. Isolate

Test the hypothesis with the cheapest decisive experiment. Bisect the change
history, binary-search the input, add one targeted log line or assertion, or
disable half the pipeline — whatever localizes the fault fastest. Each experiment
must be able to come back *no*; an experiment that can only confirm your
hypothesis proves nothing. Narrow until the fault sits on a known line.

### 5. Fix the root cause

Fix the fault the isolation step localized, not the symptom. If a change makes
the symptom disappear but you cannot say *why* it was failing, you have written a
patch, not a fix — the bug is still there, now hidden. Prefer the fix that makes
the whole class of bug impossible over the one that silences this instance.

### 6. Verify

Confirm the symptom is gone against the reproduction from phase 1, then add a
regression test that fails without the fix (hand this to `/lore:tdd`). Finally check
you did not just move the bug: re-run the surrounding suite and reason about what
else touched the fault.

## Circuit breaker

Count your fix attempts on a single bug. **After 3 failed fix attempts, STOP.**
Do not attempt a 4th.

Three failures on the same fault is not bad luck — it is evidence that your model
of the system is wrong. The bug is not where you keep looking, or the design
makes the correct fix unreachable from where you are standing. A 4th attempt from
the same mental model is very likely to fail the same way, and each blind retry
digs the hole deeper.

When the breaker trips, change altitude instead of trying again: **question the
architecture, not the line.**

- State, in writing, what you *assumed* was true that the three failures
  contradict. The wrong assumption is the actual bug.
- Widen the frame: is the fault in a different module, a shared dependency, the
  data, the environment, or the interface contract rather than the code you keep
  editing?
- Ask whether the architecture itself is forcing the bug — a leaky abstraction, a
  missing seam, two components that should not be coupled. The right fix may be a
  design change, not a code change.
- If you are a teammate under a supervisor, this is the point to escalate with
  what you have ruled out — not to spend the session on a 4th, 5th, 6th attempt.

Resetting the counter is legitimate only when you have genuinely new information
(a new reproduction, a disproven assumption, a different hypothesis) — not when
you simply want to keep trying the same thing.