# Piv Investigate Issue

Investigate a GitHub issue, fan out parallel exploration, find the root cause (5 Whys...

- Repository: https://github.com/coleam00/skills (726 stars)
- Category: Git and review
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add coleam00/skills --skill piv-investigate-issue -g -a claude-code -y`
Codex: `npx skills add coleam00/skills --skill piv-investigate-issue -g -a codex -y`
Cursor: `npx skills add coleam00/skills --skill piv-investigate-issue -g -a cursor -y`
Gemini CLI: `npx skills add coleam00/skills --skill piv-investigate-issue -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add coleam00/skills`

## Description

Investigate a GitHub issue, fan out parallel exploration, find the root cause (5 Whys, evidence-backed), and write a reviewable RCA artifact (then post a summary to the issue). The investigate step before piv-implement-issue. Use to diagnose a bug/issue before fixing it.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Investigate Issue #$ARGUMENTS (Root-Cause Analysis)

## Objective

Investigate GitHub issue #$ARGUMENTS from this repository, identify the root cause, and document findings for future implementation.

**Prerequisites:**
- Working in a local Git repository with GitHub origin
- GitHub CLI installed and authenticated (`gh auth status`)
- Valid GitHub issue ID from this repository

## Investigation Process

### 1. Fetch GitHub Issue Details

**Use GitHub CLI to retrieve issue information:**

```bash
gh issue view $ARGUMENTS
```

This fetches:
- Issue title and description
- Reporter and creation date
- Labels and status
- Comments and discussion

### 2. Explore the Codebase, fan out in parallel

Dispatch specialized agents **in parallel** (one message, multiple Task calls) so exploration is fast and the noisy
search stays out of your main context:
- **`codebase-analyst`**, trace HOW the affected code works end-to-end: integration points, data flow,
  state/side effects, error handling. Return precise `file:line` references, no suggestions.
- **`research-agent`** (a second explorer), find WHERE the relevant code lives + patterns to mirror: the error
  strings from the issue, related functions/modules, similar implementations, existing test patterns.

Merge their findings into a short map (`file:line` + why each matters) before forming the root cause. *(This is
the parallel-subagent fan-out, applied to diagnosis.)*

### 3. Review Recent History, when was it introduced?

Check recent changes to the affected areas, and pin down when the bug entered:
!`git log --oneline -20 -- [relevant-paths]`
```bash
git blame -L <start>,<end> <affected-file>   # who/when introduced the suspect lines
```
Decide: a recent **regression** vs a **long-standing** bug vs **original** behavior, it changes both the fix and the risk.

### 4. Investigate Root Cause, the 5 Whys, with evidence

The rest: https://github.com/coleam00/skills/blob/HEAD/.claude/skills/piv-investigate-issue/SKILL.md