debug

Debug

Iron law

Do not guess. Do not apply a fix until you understand the root cause. Every fix must follow from evidence. "It might be X" is not sufficient — "evidence Y proves it is X" is.

Phase 1: reproduce

Establish a minimal reproduction before doing anything else:

1. What exact input or action triggers the issue?
2. What is the expected outcome? What is the actual outcome (exact error message, full stack trace)?
3. Is it deterministic or intermittent?
4. When did it start? What changed?

If you cannot reproduce it, you cannot fix it with confidence.

Phase 2: isolate

Narrow down the location:

1. Binary search — which layer does the failure originate in?
2. Remove variables — disable features, mock dependencies one at a time.
3. Check inputs — is the problem in the data, not the code?
4. Check environment — does it fail in prod but not dev, and why specifically?

For Go: check whether go test -race reveals it; add log.Printf("[DEBUG] state=%v", state) at layer boundaries; use dlv (Delve) for interactive stepping when a print-based binary search stalls.

Phase 3: diagnose

Identify the root cause with evidence: trace the execution path from input to failure; check every assumption (types, nil-ness, ordering, timing); for panics, read the stack trace top-to-bottom — the root cause is usually the deepest frame, not the one at the top where the panic surfaced.

Phase 4: fix

1. Fix the root cause, not a symptom.
2. Write a test that would have caught this bug — it should fail without the fix and pass with it.
3. Check whether the same bug pattern exists in similar code elsewhere in the codebase.
4. Update documentation if the behavior was wrong but previously undocumented as correct.

Common Go patterns

Symptom	Likely cause	Check
nil pointer dereference	Unguarded pointer use	Add a nil check before dereference
goroutine leak	Missing stop signal	Add a context.Context or done channel
data race	Concurrent map/slice mutation	Add a mutex, or use sync.Map
context deadline exceeded	Missing timeout propagation	Pass ctx into every blocking call on the path
unexpected log output	Wrong logger instance	Check which logger got wired at construction
test flakiness	Time-dependent assertion	Use an eventually/poll pattern instead of a fixed sleep