Prp Investigate

---
description: Investigate issues and bugs — auto-detects GitHub issues vs symptoms
argument-hint: <issue-number, URL, or symptom description>
---

# Investigation Protocol

Unified investigation command that handles both GitHub issues and ad-hoc bug reports through systematic analysis.

## Investigation Philosophy

- **5 Whys for bugs** — dig to root cause, not symptoms
- **Reject conjecture** — no "likely" or "probably" without evidence
- **Codebase evidence** — reference actual files and line numbers
- **Test, don't assume** — verify each hypothesis
- **Consult git history** — `git blame` and `git log` are your friends

---

## Phase 1: CLASSIFY INPUT

Parse `$ARGUMENTS` to determine investigation mode:

| Input | Detection | Mode |
|-------|-----------|------|
| `#123` or just `123` | Matches `^#?\d+$` | **GitHub Issue** |
| GitHub URL | Contains `github.com` | **GitHub Issue** |
| Free-form text | No pattern match | **Root Cause Analysis** |

### GitHub Issue Mode

Fetch issue context:

```bash
gh issue view {number} --json number,title,body,labels,comments,author,createdAt

Extract: ISSUE_TITLE, ISSUE_BODY, ISSUE_LABELS

Classify issue type:

Type	Indicators
Bug	"doesn't work", "error", "broken", "fails"
Enhancement	"add", "improve", "support", "would be nice"
Refactor	"cleanup", "technical debt", "reorganize"
Chore	"update", "upgrade", "maintenance"
Documentation	"docs", "readme", "comments"

Root Cause Analysis Mode

Establish analysis context:

SYMPTOM: {What is happening — from $ARGUMENTS}
EXPECTED: {What should happen}
CONTEXT: {When/where it occurs}

Determine analysis depth:

Mode	When to Use
Quick	Clear error message, obvious location
Deep	Intermittent issue, unclear cause

---

Phase 2: EXPLORE

Use the Explore agent to search the codebase:

Launch Agent tool with subagent_type="Explore"

Prompt: "Investigate: {issue_title or symptom}

Search for:
1. Files related to: {keywords}
2. Similar patterns or implementations
3. Integration points that may be affected
4. Existing test coverage for affected areas
5. Recent changes to relevant files (git history)

Return actual file paths with line numbers and brief explanations."

Discovery Targets

1. Relevant Files — files mentioned in issue or matching keywords
2. Integration Points — what depends on affected code and vice versa
3. Similar Patterns — how similar issues were fixed
4. Test Structure — existing tests for the area

---

Phase 3: ANALYZE — The 5 Whys

3.1 Generate Hypotheses

Generate 2-4 competing theories ranked by likelihood:

## Hypothesis 1: {Theory Name} [Likelihood: High/Medium/Low]

**Conditions that must exist:**
- {condition 1}
- {condition 2}

**Evidence required to confirm:**
- {evidence 1}

**How to test:**
- {test method}

3.2 Execute 5 Whys

### Why #1
**Question**: Why does {symptom} occur?
**Answer**: Because {cause A}
**Evidence**: {file:line or test result}

### Why #2
**Question**: Why does {cause A} happen?
**Answer**: Because {cause B}
**Evidence**: {file:line or test result}

[Continue until root cause identified]

### Root Cause
{The fundamental issue that needs to be fixed}
**Location**: {file:line}

3.3 Validate Root Cause

Apply three validation tests:

1. Causation — Does the identified cause directly lead to the symptom?
2. Necessity — Would the symptom exist without this cause?
3. Sufficiency — Is this cause alone sufficient, or are co-factors involved?

The Ultimate Test: "If I changed THIS specific thing, would the issue vanish?"

3.4 Scope Analysis (for enhancements)

**In Scope**: {specific changes}
**Out of Scope**: {related but not included}
**Dependencies**: {what this depends on}
**Dependents**: {what depends on this}

3.5 Risk Assessment

Risk	Likelihood	Impact	Mitigation
{risk 1}	H/M/L	H/M/L	{plan}

3.6 Edge Cases

Case	Expected Behavior	Notes
{edge case}	{behavior}	{notes}

---

Phase 4: GENERATE ARTIFACT

Create artifact at .claude/PRPs/issues/{identifier}.md:

• For GitHub issues: issue-{number}.md
• For RCA: rca-{slugified-title}.md

# Investigation: {title}

**Investigated**: {date}
**Status**: Ready for Implementation
**Type**: {Bug | Enhancement | Refactor | Chore | Documentation | RCA}
**Source**: {GitHub Issue #{number} | Ad-hoc investigation}
**GitHub Issue**: {owner/repo#N or "Not linked"}

---

## Problem Statement

{Clear description of the issue}

### Reproduction (for bugs)
1. {step 1}
2. {step 2}
3. Expected: {expected}
4. Actual: {actual}

---

## Analysis

### Root Cause
{Explanation of why this happens}
**Location**: `{file}:{line}`

### Evidence Chain

1. {Symptom} occurs because {Cause 1}
   - Evidence: {file:line}
2. {Cause 1} happens because {ROOT CAUSE}
   - Evidence: {file:line}

### Git History

**Introduced in**: {commit hash} by {author} on {date}

### Impact Assessment

| Aspect | Impact |
|--------|--------|
| Users Affected | {description} |
| Code Areas | {files/modules} |
| Risk Level | {Low/Medium/High} |

---

## Implementation Plan

### Approach
{High-level approach to fixing/implementing}

### Files to Modify

| File | Change | Lines |
|------|--------|-------|
| `{path}` | {description} | {lines} |

### Implementation Steps

1. **{Step 1}**
   - {detail}
   - Validation: `{command}`

---

## Validation

### Automated
```bash
{type check command}
{lint command}
{test command}

Manual

• {manual verification step}

---

Confidence Assessment

Aspect	Level	Reasoning
Root Cause	{High/Medium/Low}	{one sentence}
Fix Approach	{High/Medium/Low}	{one sentence}
Risk	{High/Me
```