systematic-debugging

Root cause analysis for intermittent software failures requires reproducing the issue, isolating scope to the smallest path, and forming a testable hypothesis tied to specific source logic. This evidence-driven workflow prevents unverified guesses by validating fixes using original reproduction steps and regression testing.

Debugging cross-module breakages and multi-file interactions demands an evidence-first workflow that collects failure evidence, narrows scope, and produces a source-level root-cause hypothesis. A minimal verified fix is then applied and validated against original reproduction steps to ensure accuracy.

Systematically debug environment or concurrency anomalies by reproducing the failure, isolating scope, and forming a testable root-cause hypothesis constrained by SPEC.md phases. Apply a minimal verified fix, check for regressions, and document the session for traceability.

Evidence-driven debugging for complex runtime errors works without external dependencies by enforcing a reproducible workflow. It collects failure evidence, narrows scope to the smallest reproducing path, and applies a minimal fix verified by original reproduction steps and regression-safe testing.

When debugging attempts repeat without finding the root cause, an evidence-driven workflow detects unverified attribution risk and triggers escalation. It enforces source-level reasoning, original reproduction verification, and persistent documentation to break the cycle of guesswork.

Document your debugging trail for regression testing by writing debug records to docs/debug. Persistent documentation captures the root cause, the minimal fix applied, and the verification steps, ensuring full traceability and preventing future regressions.