investigate

Root cause debugging enforces an Iron Law: no fixes without identifying the underlying cause. It guides you through investigate, analyze, hypothesize, and implement phases to ensure you resolve the actual issue rather than just patching symptoms.

The best way to debug broken software is a phase-driven approach that investigates symptoms, analyzes code paths, and verifies hypotheses before suggesting fixes. This methodical root cause analysis works across any project or system environment.

You can use this root cause investigation approach for both debugging errors and performance issues. It proactively suggests investigation whenever you report unexpected behavior, troubleshooting needs, or errors in your software environment.

To start a root cause analysis, describe the bug with its symptoms and the steps to reproduce it. This triggers the investigation phase, which uses code search and data collection to guide you through identifying the problem.

This debugging method requires no specific frameworks or dependencies. It works across software projects and environments by using standard tools like Bash, Grep, and WebSearch to collect data, search code, and verify hypotheses.

You should not use systematic root cause debugging for trivial fixes or known errors where the cause is already obvious. It is designed for complex issues requiring structured investigation across symptoms and code paths before implementing a fix.