root-cause-investigator

name: root-cause-investigator description: Systematic root cause analysis for errors, bugs, and unexpected behaviors using 5-Why methodology. Use when user reports errors, build failures, test failures, performance issues, integration problems, or any "it's not working" scenarios.

Root Cause Investigator

Apply systematic 5-Why methodology to identify fundamental root causes of issues rather than treating symptoms. Guide thorough investigation through structured evidence gathering and analysis.

Activation Triggers

• errors, bugs, or unexpected behavior
• build failures or test failures
• performance issues or degradation
• integration problems
• any "it's not working" scenarios

The 5-Why Methodology

Systematically ask "why" five times to drill down to root cause:

1. Why #1: identify immediate cause (symptoms)
2. Why #2: uncover process/workflow issues
3. Why #3: find system-level problems
4. Why #4: discover design/architecture issues
5. Why #5: reveal fundamental root cause

Investigation Workflow

1. Gather Initial Context

Collect information about the issue:

## Issue Summary
[brief description of reported problem]

## Initial Symptoms
- what user is experiencing
- error messages or logs
- observable behavior

## Context Gathering
- environment details
- recent changes
- related components
- steps to reproduce

2. Apply 5-Why Analysis

Structure the investigation with progressive depth:

## 5-Why Analysis

### Why #1: [surface cause]
Evidence: [logs, errors, behavior]
Impact: [what this affects]

### Why #2: [deeper cause]
Evidence: [code, configuration]
Impact: [cascading effects]

### Why #3: [system cause]
Evidence: [architecture, dependencies]
Impact: [broader implications]

### Why #4: [process/design cause]
Evidence: [patterns, decisions]
Impact: [long-term effects]

### Why #5: [root cause]
Evidence: [fundamental issue]
Impact: [core problem]

3. Identify Root Cause

Document the fundamental issue requiring attention:

## Root Cause Identified
[the fundamental issue that needs addressing]

## Recommended Investigation Areas
- specific files to examine
- components to test
- systems to verify

Investigation Principles

1. Avoid solution bias - focus on understanding before fixing
2. Gather evidence - don't assume, verify with data
3. Consider multiple causes - issues often have multiple contributing factors
4. Document findings - clear documentation prevents repeat issues
5. Think systemically - consider broader implications
6. Question assumptions - challenge "it should work" thinking
7. Use version control - check when issue was introduced

Using Reference Materials

Load reference files as needed during investigation:

• references/patterns.md - common root cause patterns by category (configuration, race conditions, resource exhaustion, integration failures, build/deployment issues)
• references/techniques.md - investigation techniques with command examples (error analysis, code investigation, dependency analysis, environment investigation)

Best Practices

• resist proposing solutions until root cause is identified
• be thorough and methodical
• document evidence at each level of analysis
• verify assumptions with concrete data
• consider the issue from multiple perspectives (technical, environmental, architectural, external dependencies, process)

The goal is to find the fundamental cause, not just fix symptoms.