debug-mantra

Debug Mantra

Four-step discipline for any debug session. Recite verbatim, then apply in order.

Recite this — verbatim, as the first thing in your first response

Mantra:

1. First is reproducibility. Can the issue be reproduced reliably?
2. Know the fail path. Debugger first; then source trace + knob enumeration; then in-code instrumentation.
3. Question your hypothesis. What would disprove it?
4. Every run is a breadcrumb. Cross-reference all of them.

Then begin work.

1. Reproduce reliably

Build a runnable repro before anything else.

• Reliable repro → capture the exact steps, inputs, and environment as a runnable artifact: failing test, curl script, CLI invocation, replay harness.
• Flaky repro → the bug is not yet debuggable. Raise the rate first: loop the trigger, parallelise, add stress, narrow timing windows, inject sleeps. 50% flake is debuggable; 1% is not.
• No repro at all → stop. Say so explicitly. Ask the user for env access, captured artifacts (HAR, log dump, core), or permission to instrument. Do not proceed to hypothesise.

Target: a fast (1–5 s), deterministic pass/fail signal. Pin time, seed the RNG, freeze network, isolate filesystem.

2. Know the fail path

Once reproducible, find where the code breaks and what stops it from breaking. The differential narrows the search. Try in this order — escalate only when the prior tactic fails.

1. Attach a debugger. If the env supports it, attach and step to the failure site. One breakpoint beats ten logs. Do this before turning any knobs.
2. Source trace + knob enumeration. If no debugger (or it can't reach the bug), trace the code path end-to-end and list every knob that can influence the outcome:
   • config flags, env vars, feature toggles
   • branch conditions, input shape
   • timing, concurrency, build options Each knob is a candidate axis to flip in the differential. Flip one at a time.
3. In-code instrumentation. If outside knobs can't move the failure, go inside: printf / log statements at the suspected fail site, dump the relevant internal state. Tag every probe with a unique prefix (e.g. [DBG-a4f2]) so cleanup is a single grep. Let the trace show where reality diverges from your model.

3. Falsify the hypothesis

When a candidate root cause surfaces, scrutinise it before testing it.

• Does it actually explain the symptom end-to-end? Walk it through.
• What is the simplest proof? What is the cleanest disproof?
• Run the disproof first. If the hypothesis survives, it's real. If it dies, you saved yourself from chasing a phantom.
• Generate 3–5 ranked hypotheses, not one. Single-hypothesis thinking anchors on the first plausible idea.

4. Every run is a breadcrumb

Maintain a running ledger of every experiment in this session. Each entry: what changed, what happened, what it ruled in or out.

• When a new hypothesis surfaces, walk the ledger. Does it hold for every prior observation, not just the most recent?
• If any past run contradicts it, the hypothesis is wrong or incomplete — refine or discard.
• When in doubt, design the single experiment whose outcome makes it certain. Run that next, instead of churning on adjacent runs.
• Update the ledger after every run. It is your memory across the session.

Operating rules

• Recite the mantra block once per debug session, in your first response. Do not re-recite mid-session.
• Recite verbatim. Never paraphrase, shorten, or skip lines of the recital.
• If the user says "skip the mantra" → skip the recital but still apply the four steps silently.
• Apply the four steps in order:
  • Do not propose a fix before #1 is satisfied (reliable repro exists).
  • Do not start testing hypotheses before #2 has narrowed the fail path.
  • Do not commit to a hypothesis before #3 has tried to disprove it.
  • Do not declare a hypothesis correct until #4 confirms it against every prior breadcrumb.
• If you catch yourself proposing a fix without a reliable repro, stop and return to step 1.
• The mantra is a constraint you carry through the session — not advice to deliver back to the user.