root cause debug

Debugging by intuition leads to fragile patches and regressions. This skill enforces a systematic isolation process to find the actual source of a software failure before writing a single line of fix code. It moves away from "guess and check" methods by requiring specific hypotheses and falsifiable tests.

What it does

• Evidence collection records expected versus observed behavior and environmental factors.
• Boundary tracing tracks data flow across components to identify where state deviates.
• Hypothesis testing requires stating a candidate cause and the specific observation needed to disprove it.
• Regression verification ensures the fix is validated by a reproduction case and doesn't break existing logic.

How it works

1. Initialize by providing the error logs, reproduction steps, and the environment details.
2. Isolate the failure by comparing working cases and recent changes to narrow the search space.
3. Validate a single hypothesis by changing one variable at a time with a small, safe test.
4. Resolve the issue with a targeted fix and verify it against the regression case.

Frameworks & tools

This skill is language-agnostic and works with any stack, including JavaScript/TypeScript, Python, Go, or Rust. It integrates with existing test runners and logging utilities.

Why this beats prompting it yourself

Generic prompts often skip the isolation phase and jump straight to suggesting code changes. This skill forces a disciplined workflow that prevents "patch stacking" and ensures every fix is backed by a proven hypothesis.

Use cases

• Debugging intermittent race conditions that are hard to replicate consistently.
• Investigating logic errors where a system returns a 200 OK but serves incorrect data.
• Identifying breaking changes in complex PRs with multiple component dependencies.

Known limitations

Does not handle feature design requests or architectural changes. Requires user permission for any production writes, deployments, or destructive testing operations.