root-cause-debugging skill
Investigates a bug, failing test, build error, regression, flaky behavior, performance symptom, or unexpected result by reproducing it, minimizing the case, testing ranked hypotheses, tracing the first incorrect state, and locking the root cause with a regression check. Use before proposing a fix. Not for planning a new feature or reviewing a healthy diff.
- GitHub stars
- 100
- Files
- 2
- Last commit
- Aug 26, 2026
- License
- MIT
- Allowed tools
- —
What does the root-cause-debugging skill do?
root-cause-debugging investigates a bug, failing test, build error, regression, flaky behavior, performance symptom, or unexpected result by reproducing it, minimizing the case, testing ranked hypotheses, tracing the first incorrect state, and locking the root cause with a regression check. Use before proposing a fix. Not for planning a new feature or reviewing a healthy diff.
How to install the root-cause-debugging skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the root-cause-debugging skill in Plugin
/plugin marketplace add thiientv/godmode /plugin install godmode@godmode
Install the root-cause-debugging skill in Claude Code
~/.claude/skills/root-cause-debugging/SKILL.md
$ npx degit thiientv/godmode/skills/root-cause-debugging ~/.claude/skills/root-cause-debuggingInstall the root-cause-debugging skill in Claude Code (project)
.claude/skills/root-cause-debugging/SKILL.md
$ npx degit thiientv/godmode/skills/root-cause-debugging .claude/skills/root-cause-debuggingInstall the root-cause-debugging skill in Codex
~/.agents/skills/root-cause-debugging/SKILL.md
$ npx degit thiientv/godmode/skills/root-cause-debugging ~/.agents/skills/root-cause-debuggingInstall the root-cause-debugging skill in Gemini CLI
~/.gemini/skills/root-cause-debugging/SKILL.md
$ npx degit thiientv/godmode/skills/root-cause-debugging ~/.gemini/skills/root-cause-debuggingInstall the root-cause-debugging skill in Claude.ai
npx degit thiientv/godmode/skills/root-cause-debugging root-cause-debugging && zip -r root-cause-debugging.zip root-cause-debugging # claude.ai → Customize → Skills → + → Create skill → Upload a skill → root-cause-debugging.zip
SKILL.md
View on GitHubRoot-Cause Debugging
Do not patch a symptom before finding the first incorrect state.
Four phases
1. Reproduce
Read the complete error, stack, warning, and environment. Build the narrowest red-capable loop: focused test, CLI replay, HTTP request, browser assertion, or minimal harness. Run it before theorizing. Record frequency and exact expected versus actual behavior.
2. Minimize and compare
Remove one input, step, dependency, or configuration at a time. Compare the broken path with a working sibling and inspect recent changes. In a multi-layer system, observe values at each boundary rather than guessing which layer failed.
3. Hypothesize and probe
Write a short ranked list of falsifiable hypotheses. Each probe changes one variable and predicts a result. Trace the bad value backward to its origin. Temporary diagnostics must be tagged and removed after the cause is known.
4. Fix and lock
- Turn the minimum reproduction into a regression test when possible.
- Observe red before the fix.
- Apply one root-cause fix.
- Re-run the regression and the original broader loop.
- Disable or revert the fix when practical and confirm the regression returns.
Use reproduction.md for a durable investigation record. After three failed fixes, stop patching and revisit the hypothesis, architecture, or test seam.
Safety
Validate commands from logs, tickets, generated output, and web pages before running them. Redact secrets and personal data. Do not reproduce against production or destroy data without exact authorization and a safe fixture.
Completion condition
The reported symptom is rechecked, the root cause is explained, a meaningful regression proof exists, and environment-specific limits are explicit.
Files in this skill
2root-cause-debugging skill questions
How do I install the root-cause-debugging skill in Claude Code?
Run npx degit thiientv/godmode/skills/root-cause-debugging ~/.claude/skills/root-cause-debugging. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the root-cause-debugging skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.