systematic-debugging

Start by reading the full error message and stack trace, then reproduce the failure consistently with a command like pytest tests/test_module.py::test_name -v. Check recent git changes, trace the data flow to find where the bad value originates, and only then form a hypothesis and fix.

Root cause analysis means identifying why a bug happens before attempting any fix, rather than patching symptoms. It involves reading errors carefully, reproducing the issue, reviewing recent changes, gathering evidence at component boundaries, and tracing bad values upstream to their source.

Stop after three failed fix attempts. If each fix reveals new shared state or coupling in a different place, requires massive refactoring, or creates new symptoms elsewhere, the pattern itself is likely wrong and the architecture should be discussed before more fixes.

Yes, the process is designed especially for emergencies because guessing under pressure causes thrashing and rework. A systematic investigation typically resolves issues in 15-30 minutes versus hours of random fix attempts, with a much higher first-time fix rate.

Quick fixes address symptoms without understanding the underlying cause, so the real problem persists and the patch often introduces new issues. Bundling multiple changes at once also makes it impossible to isolate what worked, and untested fixes lack regression protection.