debugging-patterns

Root-cause debugging enforces a structured four-phase process: investigate the root cause first, analyze patterns in evidence, form and test hypotheses, then implement a minimal fix. This prevents patchwork solutions by gathering logs, traces, and data flow evidence across component boundaries before any change.

Apply mandatory diagnostic phases: trace failures across all components, capture evidence at each boundary, reproduce the issue consistently, and identify the single failing component. Only after root cause is confirmed do you propose and verify a fix addressing the actual problem, not symptoms.

Collect logs, traces, and data flow at component boundaries during the Root Cause Investigation phase. Document reproducibility steps and cross-component evidence before hypothesis testing. This data capture ensures you identify whether the issue originates in a specific component or emerges from interactions between systems.

Patchwork debugging skips root cause investigation and applies surface-level fixes. The structured process enforces mandatory evidence gathering and reproducibility before implementation, ensuring fixes address root causes. Verification steps confirm the fix resolves the actual failure, not just a symptom.

Yes, the four-phase workflow applies to all technical issues: test failures, production bugs, unexpected behavior, performance problems, and build or integration failures. The same root-cause investigation, pattern analysis, hypothesis testing, and verification steps work across any domain where rapid guessing tempts quick patches.

Skipping phase one violates the core law: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST. Without evidence and traced failure data, you risk implementing fixes that address symptoms rather than root causes, perpetuating patchwork debugging and creating cascading failures.