# Piv Investigate Issue

> 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.

- **Type:** Skill
- **Install:** `agentstack add skill-coleam00-skills-piv-investigate-issue`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [coleam00](https://agentstack.voostack.com/s/coleam00)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [coleam00](https://github.com/coleam00)
- **Source:** https://github.com/coleam00/skills/tree/main/.claude/skills/piv-investigate-issue

## Install

```sh
agentstack add skill-coleam00-skills-piv-investigate-issue
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 ,    # 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

Don't stop at the symptom. Chain **why → because** until you reach the specific, fixable code, and back **every link
with `file:line` evidence**:
```
WHY does  happen? → because    (evidence: file.ts:123 — )
WHY ?             → because    (evidence: file.ts:456 — )
… ROOT CAUSE:   (evidence: file.ts:789 — )
```
Watch for: input-validation gaps, unhandled edge cases, race/timing issues, wrong assumptions, missing error
handling, integration mismatches.

### 5. Assess Impact

**Determine:**
- How widespread is this issue?
- What features are affected?
- Are there workarounds?
- What is the severity?
- Could this cause data corruption or security issues?

### 6. Propose Fix Approach

**Design the solution:**
- What needs to be changed?
- Which files will be modified?
- What is the fix strategy?
- Are there alternative approaches?
- What testing is needed?
- Are there any risks or side effects?

## Output: Create RCA Document

Save analysis as: `docs/issues/issue-$ARGUMENTS.md`

### Required RCA Document Structure

```markdown
# Root Cause Analysis: GitHub Issue #$ARGUMENTS

## Issue Summary

- **GitHub Issue ID**: #$ARGUMENTS
- **Issue URL**: [Link to GitHub issue]
- **Title**: [Issue title from GitHub]
- **Reporter**: [GitHub username]
- **Status**: [Current GitHub issue status]

## Assessment

Each value needs a one-line reason grounded in the investigation (not a guess):

| Metric | Value | Reasoning |
|--------|-------|-----------|
| Severity | Critical/High/Medium/Low | user impact · workaround · scope of failure |
| Complexity | Low/Medium/High | files touched · integration points · risk |
| Confidence | High/Medium/Low | evidence quality · unknowns · assumptions |

> **Confidence is the human-attention signal:** LOW confidence = a human should look before the fix runs. Say it honestly.

## Problem Description

[Clear description of the issue]

**Expected Behavior:**
[What should happen]

**Actual Behavior:**
[What actually happens]

**Symptoms:**
- [List observable symptoms]

## Reproduction

**Steps to Reproduce:**
1. [Step 1]
2. [Step 2]
3. [Observe issue]

**Reproduction Verified:** [Yes/No]

## Root Cause

### Affected Components

- **Files**: [List of affected files with paths]
- **Functions/Classes**: [Specific code locations]
- **Dependencies**: [Any external deps involved]

### Analysis

[Detailed explanation of the root cause]

**Evidence Chain (5 Whys):**
```
WHY  → because           (evidence: file:line — snippet)
… ROOT CAUSE:   (evidence: file:line — snippet)
```

**Why This Occurs:**
[Explanation of the underlying issue]

**Code Location:**
```
[File path:line number]
[Relevant code snippet showing the issue]
```

### Related Issues

- [Any related issues or patterns]

## Impact Assessment

**Scope:**
- [How widespread is this?]

**Affected Features:**
- [List affected features]

**Severity Justification:**
[Why this severity level]

**Data/Security Concerns:**
[Any data corruption or security implications]

## Proposed Fix

### Fix Strategy

[High-level approach to fixing]

### Files to Modify

1. **[file-path]**
   - Changes: [What needs to change]
   - Reason: [Why this change fixes it]

2. **[file-path]**
   - Changes: [What needs to change]
   - Reason: [Why this change fixes it]

### Alternative Approaches

[Other possible solutions and why the proposed approach is better]

### Risks and Considerations

- [Any risks with this fix]
- [Side effects to watch for]
- [Breaking changes if any]

### Testing Requirements

**Test Cases Needed:**
1. [Test case 1 - verify fix works]
2. [Test case 2 - verify no regression]
3. [Test case 3 - edge cases]

**Validation Commands:**
```bash
[Exact commands to verify fix]
```

## Implementation Plan

[Brief overview of implementation steps]

This RCA document should be used by the `piv-implement-issue` skill.

## Next Steps

1. Review this RCA document
2. Run the `piv-implement-issue` skill with issue #$ARGUMENTS to implement the fix
3. Run the `piv-commit` skill after implementation complete
```

## Post the summary to the issue

After writing the doc, post a short version as a GitHub comment — an audit trail, and so the fix can be
triggered/tracked from the issue itself:
```bash
gh issue comment $ARGUMENTS --body ""
```

## Edge cases

- **Already closed** → report it; still write the RCA if analysis is wanted.
- **Already has a linked PR** → warn; confirm before continuing.
- **Can't pin the root cause** → set **Confidence: LOW**, document the best hypothesis + what's uncertain, and flag it for a human before any fix.
- **Scope too large** → suggest splitting into smaller issues; focus this RCA on the core problem and list the rest as out-of-scope.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [coleam00](https://github.com/coleam00)
- **Source:** [coleam00/skills](https://github.com/coleam00/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-coleam00-skills-piv-investigate-issue
- Seller: https://agentstack.voostack.com/s/coleam00
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.