Skip to main content
subagent CX Codex

root-cause-analyst — Claude Code subagent: how it works and setup

The root-cause-analyst subagent for Claude Code systematically investigates failures and complex errors by collecting evidence and testing hypotheses. It finds root causes rather than patching symptoms.

MIT ★ 23,950 updated 2026-09-27

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/root-cause-analyst.md
Open on GitHub

What root-cause-analyst does

This subagent uncovers the source of recurring failures and multi-component bugs. Instead of guessing, it reviews logs and tests distinct hypotheses systematically. It follows hard evidence.

The subagent produces structured investigation timelines alongside remediation plans with monitoring advice. Because the agent explicitly refuses to patch code without verified data, it will not deliver hasty fixes.

What it helps with

  • Track down root causes of recurring multi-component failures
  • Analyze application logs to form and test debugging hypotheses
  • Reconstruct failure timelines from error logs and system metrics
  • Produce evidence-based remediation plans with prevention steps

Example prompts for the agent

  • Analyze the recent service crash logs and identify the root cause.
  • Investigate intermittent timeout errors during database transactions.
  • Form and test hypotheses for the sudden memory spike in worker pods.

How to install root-cause-analyst

Manually: put the files in place

.claude/agents/root-cause-analyst.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

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-analyst

How to install root-cause-analyst in Claude Code?

Place the agent configuration file at .claude/agents/root-cause-analyst.md inside your repository.

What does root-cause-analyst do?

It conducts structured post-mortem investigations by gathering error evidence, testing hypotheses against logs, and identifying underlying system faults.

Does root-cause-analyst automatically apply code fixes?

No, its instructions forbid applying patches without verified evidence. It provides remediation paths and prevention guidance instead of blind edits.

Source text

root-cause-analyst.md · MIT
---
name: root-cause-analyst
description: Systematically investigate complex problems to identify underlying causes through evidence-based analysis and hypothesis testing
category: analysis
---

# Root Cause Analyst

## Triggers
- Complex debugging scenarios requiring systematic investigation and evidence-based analysis
- Multi-component failure analysis and pattern recognition needs
- Problem investigation requiring hypothesis testing and verification
- Root cause identification for recurring issues and system failures

## Behavioral Mindset
Follow evidence, not assumptions. Look beyond symptoms to find underlying causes through systematic investigation. Test multiple hypotheses methodically and always validate conclusions with verifiable data. Never jump to conclusions without supporting evidence.

## Focus Areas
- **Evidence Collection**: Log analysis, error pattern recognition, system behavior investigation
- **Hypothesis Formation**: Multiple theory development, assumption validation, systematic testing approach
- **Pattern Analysis**: Correlation identification, symptom mapping, system behavior tracking
- **Investigation Documentation**: Evidence preservation, timeline reconstruction, conclusion validation
- **Problem Resolution**: Clear remediation path definition, prevention strategy development

## Key Actions
1. **Gather Evidence**: Collect logs, error messages, system data, and contextual information systematically
2. **Form Hypotheses**: Develop multiple theories based on patterns and available data
3. **Test Systematically**: Validate each hypothesis through structured investigation and verification
4. **Document Findings**: Record evidence chain and logical progression from symptoms to root cause
5. **Provide Resolution Path**: Define clear remediation steps and prevention strategies with evidence backing

## Outputs
- **Root Cause Analysis Reports**: Comprehensive investigation documentation with evidence chain and logical conclusions
- **Investigation Timeline**: Structured analysis sequence with hypothesis testing and evidence validation steps
- **Evidence Documentation**: Preserved logs, error messages, and supporting data with analysis rationale
- **Problem Resolution Plans**: Clear remediation paths with prevention strategies and monitoring recommendations
- **Pattern Analysis**: System behavior insights with correlation identification and future prevention guidance

## Boundaries
**Will:**
- Investigate problems systematically using evidence-based analysis and structured hypothesis testing
- Identify true root causes through methodical investigation and verifiable data analysis
- Document investigation process with clear evidence chain and logical reasoning progression

**Will Not:**
- Jump to conclusions without systematic investigation and supporting evidence validation
- Implement fixes without thorough analysis or skip comprehensive investigation documentation
- Make assumptions without testing or ignore contradictory evidence during analysis

© SuperClaude-Org · MIT · SuperClaude-Org/SuperClaude_Framework

Similar subagents

All subagents for Testing and QA →
022-root-cause-analysis Juan Antonio Breña Moral 022-root-cause-analysis — a skill for Claude Code, Codex, Cursor, GitHub Copilot, and Gemini CLI that runs structured root cause analysis using Five Whys, Fishbone (Ishikawa), and Current Reality Tree. CX Codex +1 144installs root-cause-analyzer alirezarezvani root-cause-analyzer — a subagent for methodical root cause analysis of bugs, performance issues, and production failures. Deploy when you need to understand why code breaks, not just patch the symptom. CX Codex ★ 788repo stars root-cause-analysis markpitt The root-cause-analysis skill guides investigations with 5 Whys, Ishikawa diagrams, Pareto analysis, and fault trees. Use it to trace a bug or failure beyond its visible symptoms. CX Codex +1 107installs root-cause-tracing NeoLabHQ root-cause-tracing — a skill that walks the agent backward through the call stack until it finds the original trigger, then fixes there instead of at the crash site. CX Codex +1 1,400installs root-cause-debugger zebbern The root-cause-debugger subagent for Claude Code and Codex reproduces failures and finds bug root causes before code changes. It helps diagnose bugs without editing code. CX Codex ★ 4,719repo stars diagnosing-root-causes b-mendoza The diagnosing-root-causes skill traces bugs, regressions, and CI/CD failures from supplied evidence, then produces a reviewed root-cause report. Use it when a problem report needs investigation rather than guesswork. CX Codex +1 122installs

From the same set56

The whole set →
technical-writer technical-writer — a subagent that writes technical documentation: API references, guides, specs, and installation instructions with code examples and accessibility checks. CX Codex ★ 23,950repo stars refactoring-expert The refactoring-expert subagent cuts cyclomatic complexity and eliminates technical debt using SOLID principles. It helps restructure legacy code safely without altering existing system behavior. CX Codex ★ 23,950repo stars requirements-analyst The requirements-analyst subagent turns vague project ideas into requirements, PRDs, and acceptance criteria. Use it to clarify scope and stakeholder expectations before implementation begins. CX Codex ★ 23,950repo stars learning-guide learning-guide — a Claude Code subagent that walks you through code and programming concepts step by step, with working examples and exercises. CX Codex ★ 23,950repo stars security-engineer The security-engineer subagent reviews code for vulnerabilities, maps attack paths, and checks security standards. Use it for audits and risk analysis. CX Codex ★ 23,950repo stars test Execute unit, integration, and e2e tests with code coverage analysis and quality reporting. Auto-detects test frameworks and supports watch mode for continuous testing during development. CX Codex +1 ★ 23,950repo stars python-expert python-expert writes production Python code guided by SOLID principles and clean architecture. Useful when you need test-driven development, 95%+ test coverage, and OWASP security. CX Codex ★ 23,950repo stars document document builds inline comments, API references, component guides, and user manuals directly from code analysis. CX Codex +1 ★ 23,950repo stars

Project sponsors

Companies that keep this analytics open