diagnose
Diagnose against the loop, not against a reading of the code. A cause derived from reading is a hypothesis wearing a conclusion's clothes. A cause is proven when you can turn the loop red and green at will by changing the thing you claim is responsible.
Phase 1 — Confirm the loop is measuring the right failure
Run it. Observe.
- It produces the reported failure mode, not a nearby different one
- It reproduces consistently, or at the pinned rate
- The exact symptom is captured — error text, wrong value, timing
If the loop is red for a different reason than the report, you have found a second failure. Stop and split them.
Phase 2 — Minimise
Shrink to the smallest scenario still going red. Remove inputs, callers, config, data, and steps one at a time, rerunning after each cut. Keep only what is load-bearing.
Done when removing any remaining element turns the loop green.
Phase 3 — Hypothesise, then rank
Generate 3–5 hypotheses before testing any. Each must be falsifiable and predict a direction:
"If X is the cause, then changing Y turns the loop green, and changing Z makes it worse."
Rank them. Cheap-and-likely first.
Phase 4 — Instrument, one variable at a time
Each probe tests exactly one ranked prediction.
- Debugger or REPL where available — one breakpoint beats ten logs.
- Targeted logs at the boundary that distinguishes two hypotheses.
- Never "log everything and grep".
Tag every debug log uniquely ([DEBUG-a4f2]) so cleanup is one grep.
Phase 5 — Prove it
The cause is proven when you can turn the loop red and green on demand by toggling the claimed cause, and no other change is required.
Correlation is not enough. If the loop goes green when you change two things, you have not finished.
Completion — a written cause
- Cause stated in one sentence, in plain language
- File and line evidence — the exact location, quoted
- Toggle demonstrated — loop goes red and green by changing that thing alone
- Rejected hypotheses listed, each with what ruled it out
- All debug instrumentation removed
The rejected list matters. It is the cheapest thing to write now and the most expensive to reconstruct later, and classify uses it to judge novelty.
Stop conditions
No red loop, no diagnosis. If prove-the-failure did not complete, go back. Do not proceed on a described failure.
If the cause cannot be proven by toggle, say so and report the strongest hypothesis as unproven, with what would prove it. An unproven cause is a valid outcome — it goes to incident-memory and it forces classify to treat the failure as novel.
Next
classify — known or novel, and how wide the blast radius is.