What it does

The Root Cause Debugger is a high-precision diagnostic skill for AI agents. Rather than "spraying and praying" with broad code changes, it enforces an evidence-first debugging loop: reproduce, narrow scope, identify root cause, apply a surgical fix, and verify with regression coverage. This prevents the agent from making destructive "guesses" like indiscriminately upgrading dependencies or ballooning timeout values.

Why use this skill

Standard LLMs often attempt to fix bugs by rewriting large swaths of code or tweaking configurations until something works. This skill forces a developer-centric workflow that treats debugging as a science. It is particularly effective for complex issues like flaky tests, runtime exceptions, dependency conflicts, and race conditions where the "where" and "why" are not immediately obvious.

Supported Scenarios

• Failing Tests: Isolates minimal reproductions to find the boundary of failure.
• Runtime Exceptions: Traces value transformations backward to find illegal states.
• Dependency/Build Failures: Audits lockfiles and module formats before suggesting changes.
• Flaky Behavior: Proves race conditions through targeted logging and state inspection.

The output is a structured Handoff Report that documents the exact evidence found, the surgical fix applied, and the automated check added to prevent regressions.