Investigate a GitHub issue or problem - analyze codebase, create plan, post to GitHub
Investigates GitHub issues or problems by analyzing the codebase, creating a detailed implementation plan, and posting it as a GitHub comment.
/plugin marketplace add Wirasm/PRPs-agentic-eng/plugin install prp-core@prp-marketplace<issue-number|url|"description">Input: $ARGUMENTS
Investigate the issue/problem and produce a comprehensive implementation plan that:
/prp-issue-fixGolden Rule: The artifact you produce IS the specification. The implementing agent should be able to work from it without asking questions.
Check the input format:
123, #123) → GitHub issue numberhttp → GitHub URL (extract issue number)# If GitHub issue, fetch it:
gh issue view {number} --json title,body,labels,comments,state,url,author
If GitHub issue:
If free-form:
| Type | Indicators |
|---|---|
| BUG | "broken", "error", "crash", "doesn't work", stack trace |
| ENHANCEMENT | "add", "support", "feature", "would be nice" |
| REFACTOR | "clean up", "improve", "simplify", "reorganize" |
| CHORE | "update", "upgrade", "maintenance", "dependency" |
| DOCUMENTATION | "docs", "readme", "clarify", "example" |
Each assessment requires a one-sentence reasoning explaining WHY you chose that value. This reasoning must be based on concrete findings from your investigation (codebase exploration, git history, integration analysis).
For BUG issues - Severity:
| Severity | Criteria |
|---|---|
| CRITICAL | System down, data loss, security vulnerability, no workaround |
| HIGH | Major feature broken, significant user impact, difficult workaround |
| MEDIUM | Feature partially broken, moderate impact, workaround exists |
| LOW | Minor issue, cosmetic, edge case, easy workaround |
For ENHANCEMENT/REFACTOR/CHORE/DOCUMENTATION - Priority:
| Priority | Criteria |
|---|---|
| HIGH | Blocking other work, frequently requested, high user value |
| MEDIUM | Important but not urgent, moderate user value |
| LOW | Nice to have, low urgency, minimal user impact |
Complexity (based on codebase findings):
| Complexity | Criteria |
|---|---|
| HIGH | 5+ files, multiple integration points, architectural changes, high risk |
| MEDIUM | 2-4 files, some integration points, moderate risk |
| LOW | 1-2 files, isolated change, low risk |
Confidence (based on evidence quality):
| Confidence | Criteria |
|---|---|
| HIGH | Clear root cause, strong evidence, well-understood code path |
| MEDIUM | Likely root cause, some assumptions, partially understood |
| LOW | Uncertain root cause, limited evidence, many unknowns |
PHASE_1_CHECKPOINT:
Use Task tool with subagent_type="Explore":
Explore the codebase to understand the issue:
ISSUE: {title/description}
DISCOVER:
1. Files directly related to this functionality
2. How the current implementation works
3. Integration points - what calls this, what it calls
4. Similar patterns elsewhere to mirror
5. Existing test patterns for this area
6. Error handling patterns used
Return:
- File paths with specific line numbers
- Actual code snippets (not summaries)
- Dependencies and data flow
| Area | File:Lines | Notes |
|---|---|---|
| Core logic | src/x.ts:10-50 | Main function affected |
| Callers | src/y.ts:20-30 | Uses the core function |
| Types | src/types/x.ts:5-15 | Relevant interfaces |
| Tests | src/x.test.ts:1-100 | Existing test patterns |
| Similar | src/z.ts:40-60 | Pattern to mirror |
PHASE_2_CHECKPOINT:
Apply the 5 Whys:
WHY 1: Why does [symptom] occur?
→ Because [cause A]
→ Evidence: `file.ts:123` - {code snippet}
WHY 2: Why does [cause A] happen?
→ Because [cause B]
→ Evidence: {proof}
... continue until you reach fixable code ...
ROOT CAUSE: [the specific code/logic to change]
Evidence: `source.ts:456` - {the problematic code}
Check git history:
git log --oneline -10 -- {affected-file}
git blame -L {start},{end} {affected-file}
Identify:
Determine:
PHASE_3_CHECKPOINT:
mkdir -p .claude/PRPs/issues
Path: .claude/PRPs/issues/issue-{number}.md
If free-form (no issue number): .claude/PRPs/issues/investigation-{timestamp}.md
Write this structure to the artifact file.
Note on Severity vs Priority:
Important: Each assessment must include a one-sentence reasoning based on your investigation findings.
# Investigation: {Title}
**Issue**: #{number} ({url})
**Type**: {BUG|ENHANCEMENT|REFACTOR|CHORE|DOCUMENTATION}
**Investigated**: {ISO timestamp}
### Assessment
| Metric | Value | Reasoning |
| ---------- | ----------------------------- | ------------------------------------------------------------------------ |
| Severity | {CRITICAL\|HIGH\|MEDIUM\|LOW} | {Why this severity? Based on user impact, workarounds, scope of failure} |
| Complexity | {LOW\|MEDIUM\|HIGH} | {Why this complexity? Based on files affected, integration points, risk} |
| Confidence | {HIGH\|MEDIUM\|LOW} | {Why this confidence? Based on evidence quality, unknowns, assumptions} |
<!-- For non-BUG types, replace Severity row with Priority:
| Priority | {HIGH\|MEDIUM\|LOW} | {Why this priority? Based on user value, blocking status, frequency} |
-->
---
## Problem Statement
{Clear 2-3 sentence description of what's wrong or what's needed}
---
## Analysis
### Root Cause / Change Rationale
{For BUG: The 5 Whys chain with evidence}
{For ENHANCEMENT: Why this change and what it enables}
### Evidence Chain
WHY: {symptom}
↓ BECAUSE: {cause 1}
Evidence: `file.ts:123` - `{code snippet}`
↓ BECAUSE: {cause 2}
Evidence: `file.ts:456` - `{code snippet}`
↓ ROOT CAUSE: {the fixable thing}
Evidence: `file.ts:789` - `{problematic code}`
### Affected Files
| File | Lines | Action | Description |
| --------------- | ----- | ------ | -------------- |
| `src/x.ts` | 45-60 | UPDATE | {what changes} |
| `src/x.test.ts` | NEW | CREATE | {test to add} |
### Integration Points
- `src/y.ts:20` calls this function
- `src/z.ts:30` depends on this behavior
- {other dependencies}
### Git History
- **Introduced**: {commit} - {date} - "{message}"
- **Last modified**: {commit} - {date}
- **Implication**: {regression? original bug? long-standing?}
---
## Implementation Plan
### Step 1: {First change description}
**File**: `src/x.ts`
**Lines**: 45-60
**Action**: UPDATE
**Current code:**
```typescript
// Line 45-50
{actual current code}
```
Required change:
// What it should become
{the fix/change}
Why: {brief rationale}
{Same structure...}
File: src/x.test.ts
Action: {CREATE|UPDATE}
Test cases to add:
describe("{feature}", () => {
it("should {expected behavior}", () => {
// Test the fix
});
it("should handle {edge case}", () => {
// Test edge case
});
});
From codebase - mirror these exactly:
// SOURCE: src/similar.ts:20-30
// Pattern for {what this demonstrates}
{actual code snippet from codebase}
| Risk/Edge Case | Mitigation |
|---|---|
| {risk 1} | {how to handle} |
| {edge case} | {how to handle} |
bun run type-check
bun test {relevant-pattern}
bun run lint
IN SCOPE:
OUT OF SCOPE (do not touch):
.claude/PRPs/issues/issue-{number}.md
**PHASE_4_CHECKPOINT:**
- [ ] Artifact file created
- [ ] All sections filled with specific content
- [ ] Code snippets are actual (not invented)
- [ ] Steps are actionable without clarification
---
## Phase 5: COMMIT - Save Artifact
```bash
git add .claude/PRPs/issues/
git status
If changes to commit:
git commit -m "Investigate issue #{number}: {brief title}"
PHASE_5_CHECKPOINT:
Only if input was a GitHub issue (not free-form):
Format the artifact for GitHub and post:
gh issue comment {number} --body "$(cat <<'EOF'
## 🔍 Investigation: {Title}
**Type**: `{TYPE}`
### Assessment
| Metric | Value | Reasoning |
|--------|-------|-----------|
| {Severity or Priority} | `{VALUE}` | {one-sentence why} |
| Complexity | `{COMPLEXITY}` | {one-sentence why} |
| Confidence | `{CONFIDENCE}` | {one-sentence why} |
---
### Problem Statement
{problem statement from artifact}
---
### Root Cause Analysis
{evidence chain, formatted for GitHub}
---
### Implementation Plan
| Step | File | Change |
|------|------|--------|
| 1 | `src/x.ts:45` | {description} |
| 2 | `src/x.test.ts` | Add test for {case} |
<details>
<summary>📋 Detailed Implementation Steps</summary>
{detailed steps from artifact}
</details>
---
### Validation
```bash
bun run type-check && bun test {pattern} && bun run lint
To implement: /prp-issue-fix {number}
Investigated by Claude • {timestamp} EOF )"
**PHASE_6_CHECKPOINT:**
- [ ] Comment posted to GitHub (if GH issue)
- [ ] Formatting renders correctly
---
## Phase 7: REPORT - Output to User
```markdown
## Investigation Complete
**Issue**: #{number} - {title}
**Type**: {BUG|ENHANCEMENT|REFACTOR|...}
### Assessment
| Metric | Value | Reasoning |
|--------|-------|-----------|
| {Severity or Priority} | {value} | {why - based on investigation} |
| Complexity | {LOW\|MEDIUM\|HIGH} | {why - based on files/integration/risk} |
| Confidence | {HIGH\|MEDIUM\|LOW} | {why - based on evidence/unknowns} |
### Key Findings
- **Root Cause**: {one-line summary}
- **Files Affected**: {count} files
- **Estimated Changes**: {brief scope}
### Files to Modify
| File | Action |
|------|--------|
| `src/x.ts` | UPDATE |
| `src/x.test.ts` | CREATE |
### Artifact
`.claude/PRPs/issues/issue-{number}.md`
### GitHub
{Posted to issue | Skipped (free-form input)}
### Next Step
Run `/prp-issue-fix {number}` to execute the plan.