root_cause_debugger — Claude Code subagent: setup and use
The root_cause_debugger Claude Code subagent investigates failures using logs, traces, and repository context. It ranks plausible causes and lays out how to repair and verify the issue.
no license ★ 776 updated 2026-11-12
.claude/agents/root_cause_debugger.mdWhat root_cause_debugger does
root_cause_debugger examines failure evidence alongside implementation, configuration, environment, and dependency details. It ranks a small set of testable explanations, weighs evidence for and against each, and separates the underlying cause from later effects.
Its Markdown diagnosis covers reproduction conditions, symptoms, the likely causal chain, a minimal repair, and verification with regression tests. When the available evidence cannot support a root-cause choice, it says so. To add it to Claude Code, place the agent file at .claude/agents/root_cause_debugger.md.
What it helps with
- trace an error in logs or a stack trace to a likely cause
- separate the underlying fault from its downstream effects
- compare failure hypotheses with repository evidence
- plan a minimal fix and regression checks
Example prompts for the agent
- Trace this failure through the logs and repository code, then outline how to verify the cause.
- Find the most likely reason this test fails and separate it from the resulting symptoms.
- Compare the observed error with the repository configuration and propose a minimal repair.
How to install root_cause_debugger
Manually: put the files in place
.claude/agents/root_cause_debugger.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/root_cause_debugger.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/root_cause_debugger.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about root_cause_debugger
How do I install root_cause_debugger in Claude Code?
Add the agent file at .claude/agents/root_cause_debugger.md.
What does root_cause_debugger do?
It assesses failure evidence and repository context, ranks testable explanations, and produces a diagnosis with repair and verification steps.
What happens when root_cause_debugger lacks enough evidence?
It states that the evidence does not support choosing a root cause.