obra/superpowers@systematic-debugging

Root cause analysis for software bugs requires a systematic four-phase workflow: establish reproducible steps, gather layered diagnostics through targeted instrumentation, form a single hypothesis, and test minimally with a failing test case before implementing the fix.

Debugging flaky CI tests and production incidents demands cross-system diagnostics with environment validation and multi-component tracing to locate the failing layer in pipelines, services, or build systems before proposing any code changes.

To stop symptom-only patches, enforce test-first remediation by creating a minimal failing test or reproduction case before changing code, ensuring your fix targets the true root cause rather than masking the unexpected behavior.

You should escalate to an architectural review when multiple minimal-change hypothesis tests fail to resolve the issue, indicating a deeper structural flaw rather than an isolated bug within the current system design.

Systematic debugging applies across unit tests, CI builds, multi-component integrations, and production incidents, using layered evidence collection and targeted instrumentation to trace deep call-stack errors and isolate the failing layer.

Reproducing the failure reliably is mandatory because systematic debugging relies on evidence-driven investigation; without consistent reproduction steps, you cannot validate hypotheses or confirm that your targeted fix actually resolves the root cause.