root-cause-investigator git:20260217.d627b3fA

Immutable. This exact content is served forever at /api/v1/blob/eaeaeb08e6e125c1.

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