systematic-debugging

Start by reading the full error message and stack trace, then reproduce the failure consistently with a specific test command like pytest -v. Check recent git changes, trace the data flow to the source, and only then form a hypothesis and write a failing regression test before fixing.

Root cause analysis means identifying why a bug occurs rather than patching its symptoms. It involves reproducing the issue, gathering evidence at component boundaries, tracing bad values upstream through the call stack, and fixing the source instead of the symptom.

Add diagnostic instrumentation at each component boundary: log what data enters and exits each component, verify config propagation, and check state at every layer. Run once to gather evidence showing where the flow breaks, then investigate that specific component.

Stop after three failed fix attempts. If each fix reveals new coupling in a different place, requires massive refactoring, or creates new symptoms elsewhere, the pattern itself is likely wrong. Discuss architectural changes before attempting a fourth fix.

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