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.