systematic-debugging

Systematic debugging

Random fixes waste time and create new bugs. Symptom fixes are failure.

Iron law: No fixes without root-cause investigation first.

Four phases

1. Investigation (before any fix)

• Read the error message completely. Stack trace, line numbers, error codes.
• Reproduce reliably. If you can't, gather more data; do not guess.
• Check recent changes: git log, git diff, recent commits, new dependencies, config drift.
• For multi-component systems: instrument every boundary and run once before proposing fixes. The evidence shows which layer fails.
• Trace data flow backward: where did the bad value originate? Fix at the source.

2. Pattern analysis

• Find a working example in the same codebase. What works that's similar to what's broken?
• If implementing a pattern, read the reference implementation completely. Skimming guarantees bugs.
• List every difference between working and broken. "That can't matter" is a rationalization.

3. Hypothesis and minimal test

• State the hypothesis plainly: "I think X is the root cause because Y."
• Make the smallest possible change to test it. One variable at a time.
• Verify before continuing. If it didn't work: form a new hypothesis. Don't pile fixes.
• If you don't understand something, say so. Don't pretend.

4. Fix at the root

• Write a failing test for the bug first. Smallest possible reproduction.
• Implement one fix. No bundled refactoring, no "while I'm here."
• Verify: test passes, no other tests broken, issue actually resolved.
• If 3+ fixes have failed: stop. Question the architecture. Each fix revealing a new symptom in a different place is the signature of an architectural problem, not a bug.

Use greymatter to investigate

• query_blast_radius <file> — what depends on the broken thing?
• walk_flow <file> <function> — trace through to find where state goes wrong.
• find_identifier <name> — locate where a misbehaving symbol is defined.
• grep_project <pattern> — find every call site (graph edges miss textual contracts).
• search.js + read-window.js — find prior decisions and reasoning that explain why the code is the way it is.

Red flags — stop and restart at Phase 1

• "Quick fix for now, investigate later."
• "Just try changing X."
• "Probably X — let me fix that."
• Proposing a fix before tracing data flow.
• One more fix attempt after two failures.
• Each fix reveals a new problem somewhere else.

When investigation reveals "no root cause"

95% of the time this is incomplete investigation. The other 5%: timing, environment, external service. Document what you investigated, implement appropriate handling (retry, timeout, surfaced error), add monitoring for future investigation. Then stop.