Debugging

Preview

Hypothesis-driven diagnosis instead of speculative edits.

Debugging is an investigation. Pimsy forms hypotheses, ranks them by the cheapest disproving test, and stops when the evidence is conclusive.

Method#

1
Reproduce
Establish a deterministic path to the failure. Without reproduction, any fix is a guess.
2
Hypothesize
Enumerate plausible causes with the evidence each one predicts.
3
Discriminate
Run the cheapest check that eliminates the most hypotheses.
4
Localize
Narrow to the specific line or interaction, using instrumentation and bisection.
5
Explain
State the mechanism. "It works now" is not a diagnosis.
6
Fix and prove
Apply the minimal change and demonstrate the failure path is closed.

Hypothesis ledger from a trace

{
  class="tok-str">"symptom": class="tok-str">"class="tok-num">5% of checkout sessions return class="tok-num">500 under load",
  class="tok-str">"hypotheses": [
    { class="tok-str">"id": class="tok-str">"h1", class="tok-str">"claim": class="tok-str">"Connection pool exhaustion", class="tok-str">"status": class="tok-str">"supported",
      class="tok-str">"evidence": [class="tok-str">"pool wait p99 = class="tok-num">4.2s at peak", class="tok-str">"errors correlate r=class="tok-num">0.91 with pool saturation"] },
    { class="tok-str">"id": class="tok-str">"h2", class="tok-str">"claim": class="tok-str">"Upstream tax API timeouts", class="tok-str">"status": class="tok-str">"rejected",
      class="tok-str">"evidence": [class="tok-str">"upstream p99 = 180ms across the window"] },
    { class="tok-str">"id": class="tok-str">"h3", class="tok-str">"claim": class="tok-str">"Serialization deadlock", class="tok-str">"status": class="tok-str">"rejected",
      class="tok-str">"evidence": [class="tok-str">"no lock waits recorded in the DB log"] }
  ],
  class="tok-str">"conclusion": class="tok-str">"h1 — pool sized for class="tok-num">2 workers, deployment runs class="tok-num">8"
}

Last updated 2026-09-01