debug

Root-cause debugging uses an investigation-first workflow to collect evidence, trace data flow, and formulate a confirmed hypothesis before writing code, ensuring the true source of the software problem is surfaced rather than just treating symptoms.

To debug a complex test failure, you collect signals and logs to define a verifiable hypothesis, perform trace analysis, and prepare regression-test scaffolding to validate the fix while ensuring safety and reproducibility before handoff to fix mode.

Trace analysis and data-flow tracing are needed when a failing symptom lacks an obvious cause, requiring you to gather execution signals and map data movement across the project to build a confirmed root-cause hypothesis.

You hand off a confirmed bug diagnosis safely by documenting the investigation scope and root-cause hypothesis, specifying requirements for tools and steps, and preparing regression tests to ensure the fix mode is reproducible.

Investigation-first debugging applies across general software projects, automated workflows, and test failures by guiding evidence gathering and trace analysis to surface the root cause before transitioning to fix mode.

Writing a regression test before fixing a bug validates the diagnosis, ensures the identified root-cause hypothesis is accurate, and provides scaffolding to confirm the fix resolves the issue without introducing new regressions.