investigate

Systematic root-cause debugging identifies underlying causes of software defects rather than just addressing symptoms. You need it when users report errors, unexpected behavior, or code failures, ensuring you fix the actual problem instead of patching superficial issues.

Debug software defects by following a five-phase workflow: investigate, analyze, hypothesize, implement, and verify. This structured process guides you from initial evidence collection through pattern analysis and hypothesis testing to implementing and validating a permanent bug fix.

Collect evidence and reproduce bugs by gathering logs, traces, and code references. Use code search utilities like Grep and Read to trace through the codebase, mapping reported symptoms to their underlying root causes systematically.

Align stakeholders on a repair plan using structured communication templates. These templates gather user input during the debugging workflow, ensuring clear communication of evidence, hypotheses, and implementation steps across the end-to-end investigation process.

Hypothesis testing during pattern analysis validates suspected causes by mapping collected evidence against code behavior. It enforces a structured approach to verify assumptions before implementation, ensuring the identified root cause is accurate and reproducible.

Phase-driven debugging relies on accurate evidence gathering and reproducibility. If logs, traces, or code references are incomplete, mapping symptoms to root causes becomes difficult, making hypothesis testing less effective for non-deterministic or complex codebase failures.