# Root Cause Debug

> Diagnose a bug, regression, failing test, build failure, or incorrect behavior. Use before changing code when the cause has not been demonstrated.

- Skill: `trugurpala/root-cause-debug` (Agent Skill)
- Install (CLI): `npx skillmds@latest add trugurpala/root-cause-debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/trugurpala/root-cause-debug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: trugurpala (https://skillmd.com/u/trugurpala)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/trugurpala/root-cause-debug

---


# Root-Cause Debugging

1. Reproduce the failure with the smallest credible command or scenario.
2. Capture the observed error and distinguish it from pre-existing noise.
3. Trace the failing path to the owning boundary.
4. Form explicit hypotheses and test the cheapest discriminating hypothesis first.
5. Change code only after evidence supports a cause.
6. Add or strengthen a regression test when practical.
7. Re-run the reproducer, targeted tests, and relevant broader gates.

Do not shotgun-edit multiple suspected causes.
Do not claim a root cause that was not demonstrated.