debug

Follow a four-phase process: read the full error and reproduce it reliably, compare the broken code against a working example in the same codebase, write one hypothesis in a debug log, then test it with the smallest possible change. Never edit code before the log exists.

Root cause analysis traces a failure back to its origin in the data flow or call stack rather than patching the symptom. It involves reading complete stack traces, inspecting recent changes with git log and git diff, and fixing the problem at its source.

Stop after three failed hypotheses. Repeated failures signal an architectural problem such as coupling or shared-state issues, not a simple bug. At that point, discuss refactoring and record a new architecture decision instead of continuing to patch.

A written log forces a concrete hypothesis before any change, preventing guess-and-check loops where you cannot tell which fix worked. It also creates an auditable record in docs/06-debug-logs/ that captures the symptom, investigation findings, and confirmed resolution.

Yes, it activates specifically when a test fails twice in the TDD green phase or a quick fix does not work. After the root cause is confirmed and fixed, it verifies all previously passing tests still pass before returning to the build workflow.