debug

A bug is a falsified assumption. Find the assumption, falsify it deliberately, observe the divergence, narrow until one line owns the lie. No speculation, no shotgun edits, no "fix and rerun" guessing.

When to Apply / NOT

Apply: test fails and cause unclear; production stack trace; intermittent / flaky behavior; wrong output without crash; regression after known commit window; heisenbug.

NOT apply: performance regression with correct outputs; security defect; symptom obvious from one-line read; architectural confusion.

Anti-patterns

• Shotgun debugging: editing several files hoping one fixes it.
• Print-and-rerun: adding logs without a target observation.
• Premature fix: patching symptom before isolating root cause.
• Ignoring the trace: stack frames are evidence.
• Changing two variables at once: defeats falsification.
• Deleting the failing test: capturing the bug is the asset.

Hypothesis Loop (language-neutral)

1. Observe — Reproduce the failure deterministically.
2. Trace — Read the failure artifact (stack, log, core dump).
3. Hypothesize — One falsifiable claim. Rank hypotheses by likelihood.
4. Instrument — Insert minimum probe (breakpoint, structured log, assertion).
5. Run — Execute the minimal repro.
6. Confirm or refute — If refuted, demote and pick next hypothesis.
7. Narrow — Binary-search the suspect range. Use git bisect for regressions.
8. Confirm root cause — Inverse test: removing/altering the cause must restore correctness.
9. Hand off — Forward to TDD: minimal repro becomes permanent failing test.

Stack-Trace Reading

• Top frame is innermost: the failure point.
• Cause vs context: An exception's caused by chain encodes why; the stack encodes where.
• Async traces: virtual stacks drop frames between awaits — capture causal context.
• Symbol fidelity: Strip-mode binaries lose frame names. Build with debug info.
• Inlined / optimized frames: <inlined> markers signal source-line-to-instruction map is approximate.