---
name: Deep Root Cause Analysis
description: Conduct team investigation or inline analysis to identify root cause
next_step: step-02-resolve
---

## Step 01: Deep Root Cause Analysis

### Objective
Identify the root cause of the bug through systematic investigation, using either inline analysis or parallel agent teamwork.

### Pre-Step: Decision from step-00-init

Based on decision matrix from step-00:
- **Inline path**: Investigate directly using grep, code review, log analysis
- **Team path**: Create team and spawn parallel investigators

---

### Path A: Team Investigation (if needed)

#### 2.1 Create Team

```yaml
TeamCreate:
  team_name: "debug-investigate"
  description: "Parallel bug investigation"
```

#### 2.2 Spawn Teammates (single message, parallel Task calls)

Spawn all relevant teammates simultaneously:

**code-investigator** (`general-purpose`, haiku)
```
You are a code investigator on the debug team.

## Bug Context
Error: {error_description}
Stack trace: {stack_trace}

## Mission
1. Locate the error source in code (from stack trace)
2. Find related error handling patterns
3. Identify similar code that works correctly (for comparison)
4. Check recent commits on affected files (git log, git blame)
5. Search for similar error patterns elsewhere in codebase

## Communication
- Send FINDING messages to team-lead for each significant discovery:
  SendMessage(type: "message", recipient: "team-lead", content: "FINDING: {description with file:line}", summary: "Found {short}")
- When done:
  SendMessage(type: "message", recipient: "team-lead", content: "INVESTIGATION_COMPLETE: {summary}", summary: "Code investigation done")
- If team-lead sends a LEAD_HINT, follow that direction

## Rules
- Bash ONLY for: git log, git blame, git diff (NEVER modify code)
- Report file paths with line numbers
- Be precise and factual
```

**doc-researcher** (`general-purpose`, haiku)
```
You are a documentation researcher on the debug team.

## Bug Context
Error: {error_description}
Libraries: {libraries_in_stacktrace}

## Mission
1. Research documentation for libraries in the stack trace
2. Find known issues or breaking changes
3. Find correct usage patterns
4. Search for similar issues reported online
5. Look for migration guides if version issues suspected

## Communication
- Send FINDING messages to team-lead for each discovery:
  SendMessage(type: "message", recipient: "team-lead", content: "FINDING: {description}", summary: "Found {short}")
- When done:
  SendMessage(type: "message", recipient: "team-lead", content: "INVESTIGATION_COMPLETE: {summary}", summary: "Doc research done")
- If team-lead sends a LEAD_HINT, follow that direction
```

**data-inspector** (`general-purpose`, haiku) — *only if bug involves data/persistence/DB*
```
You are a READ-ONLY database inspector on the debug team.

## Bug Context
Error: {error_description}

## ABSOLUTE RESTRICTIONS
YOU MUST NEVER EXECUTE: INSERT, UPDATE, DELETE, MERGE, TRUNCATE, DROP, ALTER, CREATE, EXEC, dotnet ef database update, dotnet ef migrations
YOU MAY ONLY EXECUTE: SELECT, INFORMATION_SCHEMA, sys.* views, sp_help

## Mission
1. Find connection string (appsettings.json, appsettings.Development.json)
2. Check record existence and field values for affected entities
3. Verify FK integrity (orphaned records)
4. Check tenant isolation (TenantId on all records)
5. Verify soft delete and audit field consistency
6. Compare schema vs expected EF Core model

## Communication
- Send FINDING messages to team-lead for each data anomaly:
  SendMessage(type: "message", recipient: "team-lead", content: "FINDING: {description}", summary: "Data issue {short}")
- When done:
  SendMessage(type: "message", recipient: "team-lead", content: "INVESTIGATION_COMPLETE: {summary}", summary: "DB inspection done")
- If team-lead sends a LEAD_HINT, follow that direction

## Rules
- Bash ONLY for SELECT queries (NEVER modify data)
- If a fix is needed, DESCRIBE it — NEVER execute it
- Mask sensitive data (passwords, tokens, PII)
- Limit results with TOP/LIMIT
```

#### 2.3 Orchestrate — Lead Actions During Investigation

While teammates investigate in parallel:

- **Monitor** incoming `FINDING` messages from agents
- **Cross-reference** findings between agents (code ↔ data ↔ docs)
- **Send `LEAD_HINT`** when one agent's finding informs another:
  ```yaml
  SendMessage:
    type: "message"
    recipient: "data-inspector"
    content: "LEAD_HINT: code-investigator found null FK at OrderService.cs:45 — check if Customer records exist for affected OrderIds"
    summary: "Investigate FK from code finding"
  ```
- **Additional inline investigation**: Grep for error patterns, check related files, examine recent commits

#### 2.4 Aggregate & Shutdown

Wait for all `INVESTIGATION_COMPLETE` messages, then:

1. Collect all `FINDING` messages from each agent
2. Cross-reference: code issues ↔ data anomalies ↔ documentation
3. Shutdown teammates:
   ```yaml
   SendMessage:
     type: "shutdown_request"
     recipient: "{each-teammate}"
     content: "Investigation complete"
   # Wait for shutdown_response, then:
   TeamDelete
   ```

---

### Path B: Inline Investigation (if team NOT needed)

#### Log Analysis
- Extract timestamps, error codes, stack traces
- Identify error propagation patterns
- Look for correlation with system events

#### Code Investigation
- Trace execution path to error location
- Check variable states and data flow
- Examine error handling patterns
- Review recent commits affecting the area

---

### ULTRA-THINK: Deep Root Cause Analysis

**THINK DEEPLY** about the error chain: symptoms → immediate cause → root cause

Aggregate all team findings (or inline evidence) and consider:
- Code logic errors
- Configuration issues
- Data integrity problems (from data-inspector findings)
- Environment problems
- Race conditions
- Memory issues
- Network problems

**CRITICAL**: Map the complete failure path from root cause to visible symptom
Validate hypotheses against evidence from ALL agents

#### WHY Technique

Ask "why" at least 5 times:
1. Why did the error occur? → X happened
2. Why did X happen? → Y was in invalid state
3. Why was Y invalid? → Z didn't initialize properly
4. Why didn't Z initialize? → A dependency was missing
5. Why was dependency missing? → Configuration error

### Root Cause Mapping
- **WHY technique**: Ask "why" 5 times minimum
- Consider environmental factors
- Check for timing/concurrency issues
- Validate assumptions about data/state
- Cross-reference team findings (code ↔ data ↔ docs)

### Analysis Success Checklist

- [ ] Root cause hypothesis formulated with evidence
- [ ] Evidence validates hypothesis (from all sources)
- [ ] Team findings cross-referenced and reconciled
- [ ] WHY chain completed (5+ levels)
- [ ] Environmental/config factors considered
- [ ] Edge cases and timing issues identified
- [ ] Team (if used) properly shut down

### Success Metrics

- Root cause identified with supporting evidence (not just symptoms)
- All team findings integrated and validated
- Complete failure path mapped from root cause to visible symptom
- Investigation approach justified and documented
- Ready to move to resolution phase

### Next Step

Proceed to **step-02-resolve** for implementation and verification.
