Systematic Debugging

Fix the cause, not the symptom. Fast guesses are allowed only after the failure is reproduced and falsifiable.

When to activate

• Crash, timeout, flaky test, exploit instability, silent corruption, race, or environment-specific failure.
• Two attempted fixes did not solve the issue.
• The observed failure is far from the likely source: heap corruption, async timing, protocol state, ABI mismatch, or bad fixture isolation.

Workflow

1. Reproduce: get the smallest command/input that fails. Capture environment, seed, target version, and exact output.
2. Classify: assertion failure, crash, hang, race, memory/UB, network/protocol, config, permission, or tool misuse.
3. Trace backward: follow data/control flow from symptom to first wrong state.
4. Form one hypothesis: state what would prove or disprove it.
5. Instrument narrowly: log, breakpoint, sanitizer, packet trace, syscall trace, or debugger watchpoint at the boundary of uncertainty.
6. Patch minimally: fix the root cause and remove temporary instrumentation.
7. Regression gate: add or update a test/reproducer, then run focused and relevant broader checks.