Diagnose — From Symptom to Proven Cause

An evidence-driven method for root-causing a failure. The posture comes from fable-mindset's Diagnosis moment: pattern-match is not diagnosis. Use the techniques below to resolve uncertainty; do not perform a step whose question the evidence already answers. Say the leitwörter as you work; they are the checkpoints.

The procedure

1. Reproduce first. A bug you cannot reproduce is a report, not a diagnosis. Capture the exact failing command and its exact output before anything else — that pair is the ground truth every later step is measured against. If you cannot reproduce it, say so and stop guessing (see the pipeline return below).
2. Minimize when needed. Shrink the input, scope, or setup when doing so separates possible causes or produces a usable regression case. Keep an existing reproduction when it already establishes the mechanism.
3. Read the actual error and the actual code path. The real message, the real stack, the real code it names — before hypothesizing. The tell that you skipped this: your explanation describes similar bugs ("this is usually…") instead of facts from this one.
4. Resolve competing hypotheses. When more than one cause fits, choose the cheapest discriminating probe that separates them. Do not invent alternatives after the existing evidence establishes one cause.
5. Instrument only for missing evidence. Use existing logs, values, code paths, or a failing test as the artifact of proof when sufficient. Add targeted logging, assertions, or breakpoints only to resolve the remaining uncertainty. Prefer probes that preserve failure state; instrumentation can itself affect timing or behavior.
6. Fix the cause, not the symptom. Before editing, state why this fix addresses the mechanism the artifact proved — "the fix clears the leaked connection in the retry path, which is the mechanism behind the pool exhaustion" — not merely why it makes the symptom stop.
7. Regression-test. Encode the failure as a test that fails before the fix and passes after — both runs observed, not assumed. Hand the write-the-test loop to tdd; the reproduction from step 1 is its red.
8. Clean up. Remove any temporary instrumentation added during diagnosis. Keep only what earns permanent residence (an assertion stating a real invariant); scratch repros and debug logging go.

Rules