systematic-debugging

name	systematic-debugging
description	Use when: a bug is unclear and you need a hypothesis-driven loop instead of random edits.

Goal: find the true cause with evidence before changing code.

Use for:

• intermittent, surprising, or hard-to-reproduce failures
• bugs that resisted a first guess fix
• behavior that contradicts your mental model

Workflow:

1. Reproduce reliably; capture the smallest failing case.
2. Observe exact symptoms, errors, and recent changes.
3. Form one falsifiable hypothesis about the cause.
4. Design the cheapest test that would prove it wrong.
5. Run it, read the evidence, keep or discard the hypothesis.
6. Once confirmed, fix the cause and verify the original case.

Tactics:

• bisect inputs, commits, or code paths to localize
• add temporary logging at the boundary, not everywhere
• check assumptions about data, types, and timing first

Rules:

• one hypothesis at a time; do not change several things at once
• never claim a fix without reproducing then re-verifying
• treat a passing run after a guess as luck until explained
• remove temporary instrumentation when done