investigate

name	investigate
description	Systematically diagnose a bug via structured root cause analysis

Systematically investigate and diagnose a bug or issue using structured root cause analysis.

Issue: the task/scope the user described when invoking this skill (if none given, ask or infer from context)

Phase 1: Gather Evidence

• Grep for error messages, stack traces, related keywords in the codebase.
• Check recent git history for related changes. Clamp N to available history so this doesn't fail on repos with fewer than 5 commits: N=$(( $(git rev-list --count HEAD) - 1 )); [ $N -gt 5 ] && N=5; if N is 0 (single commit), fall back to inspecting git log --oneline / git show. Then git log --oneline -$N and git diff HEAD~$N.
• Read log files, error outputs, or console messages if provided.

Phase 2: Reproduce

1. Identify the reproduction path from gathered evidence.
2. Runtime error → find the entry point (test, script, URL), run it, capture full output.
3. Build error → run the build, capture output.
4. Logic error → write a minimal failing test that demonstrates the bug.
5. Document: Expected behavior vs Actual behavior.

Phase 3: Root Cause Analysis

Apply the 5 Whys:

Why did [symptom] happen? → Because [cause 1]
  → Why? Because [cause 2] → ... → Because [root cause]

Identify: Root cause, Contributing factors, Blast radius (what else the same root cause affects).

Phase 4: Fix

1. Implement the fix targeting the root cause (not symptoms).
2. If it touches multiple files, apply in dependency order.
3. Run the Phase 2 reproduction → verify it passes.
4. Run the full test suite → verify no regressions.

Phase 5: Prevent

1. If no test existed for this case, write one.
2. Check for similar patterns elsewhere: grep -rn "similar_pattern".
3. If systemic, suggest a lint rule or architectural change.

Phase 6: Report

## Investigation Report
### Issue
[one-line description]
### Reproduction
[steps]
### Root Cause
[5 Whys result]
### Fix Applied
- [file:line] — [what changed and why]
### Tests Added
- [test file] — [what it covers]
### Prevention
- [recommendations]

Rules

• NEVER guess. Every conclusion must be backed by evidence (log output, grep result, test failure).
• Reproduce FIRST, then diagnose. No fix without reproduction.
• Fix the root cause, not the symptom.
• Always add a test that would have caught this bug.
• If you can't reproduce, say so clearly and list what you tried.