| name | lore-workflow: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-workflow: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-workflow: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.
