| name | hypothesis-driven-debugging |
|---|---|
| description | Debug intermittent, hard-to-reproduce, or poorly understood failures by generating ranked hypotheses and building small throwaway diagnostic utilities to test them one at a time. Use when: a bug is flaky, non-deterministic, or only happens in certain environments; a race condition, timing issue, or state-management bug is suspected; logs are insufficient and the failure cannot be reproduced on demand; previous fix attempts did not stick; the user says 'sometimes', 'randomly', 'intermittently', 'can't reproduce', 'works locally but not in CI', or asks to find a root cause. DO NOT USE FOR: deterministic errors with a clear stack trace, compile/type errors, or failing tests with obvious assertions — fix those directly. |
Do not try to find and fix the bug in one shot. Instead, run tight loops: hypothesize, instrument, observe, discard. Throwaway diagnostic tooling is cheap to generate, so build it free