Root Cause Analysis
Dispatch 3-7 specialized RCA agents in parallel to investigate a problem from different angles, then synthesize findings into a comprehensive report.
Workflow
1. Parse and Size the Swarm
Given a problem_statement:
- Infer agent count from problem complexity (breadth of domains, surface area, symptoms)
- Set
agents_count = clamp(inferred_agents, 3, 7) - always use at least 3 agents
- Select focus areas from the taxonomy below - ensure complementary coverage
- Output chosen count, focus areas, and rationale to console
2. Focus Area Taxonomy
Select areas based on problem characteristics. Mix layers and concerns as needed.
Tech Layers:
UI/Presentation - Frontend components, rendering, user interactionAPI/Backend - Endpoints, request handling, response formationData/Database - Queries, schemas, data integrity, persistenceConfig/Infrastructure - Environment, deployment, external servicesDependencies - Third-party libs, version conflicts, compatibility
Concerns (Cross-cutting):
State Management - Application state, caching, synchronizationBusiness Logic - Domain rules, validation, workflowsIntegration - Service boundaries, contracts, data transformationPerformance - Latency, throughput, resource utilizationSecurity - Auth, authz, data protection, input validation
3. Dispatch Agents (Parallel)
Use the Task tool with subagent_type="rca" for each agent. Include these headers in each prompt:
<FOCUS_AREA>[Selected Area from Taxonomy]</FOCUS_AREA>
<PROBLEM_STATEMENT>
[Problem statement verbatim]
</PROBLEM_STATEMENT>
Ensure focus areas are complementary - cover different layers/concerns to maximize investigative breadth.
4. Collect and Synthesize
After all agents return their <rca_findings> XML blocks:
- Parse - Extract
<evidence>, <observations>, and <layer_status> from each agent's XML
- Collect - Gather all evidence items into a unified view, grouped by type
- Cross-Reference - Look for:
- Multiple agents pointing to same location/component (convergence)
- Contradictory observations (indicates complexity)
- Cleared layers (narrows the search)
- Weigh - Observations with
confidence="high" from multiple agents carry more weight
- Check Status - Which layers are
suspect vs cleared vs inconclusive?
- Determine Verdict:
- Root cause identified (high confidence) - multiple agents converge
- Root cause suspected (medium confidence) - single agent found it, others cleared
- Inconclusive (low confidence) - need more investigation
5. Render Report
Use the template in references/report-template.md.
Resources
- references/agent-prompt.md - The RCA agent system prompt for Task tool dispatches
- references/report-template.md - The final report template structure
1---2name: rca-analysis3description: Perform Root Cause Analysis using a multi-agent swarm approach. Use when investigating bugs, failures, performance issues, or any problem requiring systematic diagnosis. Triggers on requests like "why is X failing", "debug this issue", "find the root cause", "investigate this problem", or explicit RCA requests.4---5
6# Root Cause Analysis
7
8Dispatch 3-7 specialized RCA agents in parallel to investigate a problem from different angles, then synthesize findings into a comprehensive report.
9
10## Workflow
11
12### 1. Parse and Size the Swarm
13
14Given a `problem_statement`:
15- Infer agent count from problem complexity (breadth of domains, surface area, symptoms)
16- Set `agents_count = clamp(inferred_agents, 3, 7)` - always use at least 3 agents
17- Select focus areas from the taxonomy below - ensure complementary coverage
18- Output chosen count, focus areas, and rationale to console
19
20### 2. Focus Area Taxonomy
21
22Select areas based on problem characteristics. Mix layers and concerns as needed.
23
24**Tech Layers:**
25- `UI/Presentation` - Frontend components, rendering, user interaction
26- `API/Backend` - Endpoints, request handling, response formation
27- `Data/Database` - Queries, schemas, data integrity, persistence
28- `Config/Infrastructure` - Environment, deployment, external services
29- `Dependencies` - Third-party libs, version conflicts, compatibility
30
31**Concerns (Cross-cutting):**
32- `State Management` - Application state, caching, synchronization
33- `Business Logic` - Domain rules, validation, workflows
34- `Integration` - Service boundaries, contracts, data transformation
35- `Performance` - Latency, throughput, resource utilization
36- `Security` - Auth, authz, data protection, input validation
37
38### 3. Dispatch Agents (Parallel)
39
40Use the Task tool with `subagent_type="rca"` for each agent. Include these headers in each prompt:
41
42```
43<FOCUS_AREA>[Selected Area from Taxonomy]</FOCUS_AREA>
44
45<PROBLEM_STATEMENT>
46[Problem statement verbatim]
47</PROBLEM_STATEMENT>
48```
49
50Ensure focus areas are complementary - cover different layers/concerns to maximize investigative breadth.
51
52### 4. Collect and Synthesize
53
54After all agents return their `<rca_findings>` XML blocks:
55
56- **Parse** - Extract `<evidence>`, `<observations>`, and `<layer_status>` from each agent's XML
57- **Collect** - Gather all evidence items into a unified view, grouped by type
58- **Cross-Reference** - Look for:
59 - Multiple agents pointing to same location/component (convergence)
60 - Contradictory observations (indicates complexity)
61 - Cleared layers (narrows the search)
62- **Weigh** - Observations with `confidence="high"` from multiple agents carry more weight
63- **Check Status** - Which layers are `suspect` vs `cleared` vs `inconclusive`?
64- **Determine Verdict:**
65 - Root cause identified (high confidence) - multiple agents converge
66 - Root cause suspected (medium confidence) - single agent found it, others cleared
67 - Inconclusive (low confidence) - need more investigation
68
69### 5. Render Report
70
71Use the template in [references/report-template.md](references/report-template.md).
72
73## Resources
74
75- **references/agent-prompt.md** - The RCA agent system prompt for Task tool dispatches
76- **references/report-template.md** - The final report template structure
majiayu000