| name | systematic-debugging |
| description | Apply systematic debugging methodology: reproduction, hypothesis, experiment, root cause, fix verification |
| category | software-development |
Systematic Debugging
Do not guess. Form hypotheses, design experiments, eliminate candidates, converge on root cause through observation.
The debugging loop
OBSERVE → HYPOTHESISE → EXPERIMENT → ELIMINATE → CONVERGE
Never skip to EXPERIMENT without OBSERVE. Never fix without CONVERGE.
Phase 1: OBSERVE — reproduce the bug
- Write a reproduction recipe — exact steps, inputs, environment.
- Confirm deterministic (always fails) vs intermittent (% failure rate).
- Find the smallest reproduction — strip everything not needed to trigger the bug.
- Capture: error message, stack trace, logs, HTTP request/response, query.
Phase 2: HYPOTHESISE — list candidate causes
Write every possible cause. Rank by:
- Proximity to the failure point
- Recent changes (last deploy, last config change)
- Complexity (more complex code = more places to hide bugs)
Phase 3: EXPERIMENT — test one hypothesis at a time
Hypothesis: Redis is evicting sessions under memory pressure
Experiment: redis-cli INFO memory | grep used_memory_human; redis-cli MONITOR | grep DEL
Expected if TRUE: memory near maxmemory, DEL commands on session keys
Expected if FALSE: memory headroom, no unexpected DELs
Result: ...
Never change two things at once. One variable per experiment.
Phase 4: ELIMINATE — cross off falsified hypotheses
- FALSIFIED — evidence rules it out
- CONFIRMED — evidence supports it
- INCONCLUSIVE — need more data
Stop when exactly one hypothesis is CONFIRMED and all others FALSIFIED.
Phase 5: CONVERGE — fix at root cause
- Write a failing test that reproduces the bug.
- Implement the fix.
- Confirm the test now passes.
- Check for similar bugs in adjacent code.
Debugging tools
| Situation | Tool |
|---|
| Slow code path | Profiler (node --prof, py-spy) |
| Memory leak | Heap snapshot (Chrome DevTools) |
| Network issue | tcpdump, curl -v |
| DB slow query | EXPLAIN ANALYZE |
| Race condition | Thread sanitiser, stress test |
| Intermittent failure | Log correlation by request ID |
Rules
- Never assume — every assumption is an untested hypothesis.
- Reproduce first — if you can't reproduce it, say so.
- Binary search — midpoint log to halve the search space.
- Read the error message — 40% of bugs solved this way.
- Check recent changes —
git log --oneline -20 before anything else.
- Take notes — a session without notes wastes the next session.
Describe the bug (symptoms, error, stack trace, recent changes) and I will guide you through systematic diagnosis.
