| name | diagnose-loop |
| description | Use when a bug, flaky test, unexpected runtime behavior, or contradiction between code and observed output needs disciplined debugging before fixing. |
Diagnose Loop
Overview
Debug with evidence, not optimism. The fix should follow a reproduced failure and a tested hypothesis.
When to Use
- A test fails or flakes.
- Logs and behavior contradict expectations.
- A previous fix did not hold.
- The root cause is unknown.
Workflow
- Build the smallest feedback loop that makes the bug visible.
Improve it until it is fast enough and deterministic enough to trust.
- Reproduce the failure and record the exact symptom.
- Narrow the scope: input, environment, component, or commit range.
- List 2-3 plausible hypotheses, then test one at a time.
Show the ranked list to the user before testing when that checkpoint is cheap.
- Add the smallest useful instrumentation.
- Confirm or kill the hypothesis with evidence.
- Apply the narrowest fix that matches the proven cause.
- Add a regression test when there is a reliable seam; otherwise rerun the feedback loop and document the missing seam.
Rules
- Do not patch first and explain later.
- Do not keep multiple active hypotheses in flight.
- Change one variable at a time when instrumenting.
- Tag temporary debug instrumentation with a unique prefix so cleanup is mechanical.
- Prefer checking real contracts, test fixtures, and runtime state over guesswork.
- If the bug is flaky, first improve the feedback loop before changing code.
- Aim to raise reproduction rate, not necessarily to reach 100%.
- If reproduction is impossible, state the missing evidence clearly.
- Before done, remove temporary instrumentation and rerun the original repro.
