Investigate a bug using the 5 Whys root cause analysis technique. Fetches ticket details from JIRA (if a ticket ID is provided), checks for previous investigation reports, defines Fix Verification Criteria before digging in, traces the bug across frontend and backend repos, and generates a structured investigation report with timeline and recommendations. Requires jira CLI if using a ticket ID.
Investigate a bug using the 5 Whys root cause analysis technique. Fetches ticket details from JIRA (if a ticket ID is provided), checks for previous investigation reports, defines Fix Verification Criteria before digging in, traces the bug across frontend and backend repos, and generates a structured investigation report with timeline and recommendations. Requires jira CLI if using a ticket ID.
Bug Investigation - 5 Whys Root Cause Analysis
Investigate a bug using the 5 Whys technique to identify root causes, then create a comprehensive analysis report.
Bug ID: $ARGUMENTS (JIRA issue key, e.g., BUG-1234 — or leave blank to describe manually)
Philosophy: Verification-Driven Bug Fixing
Why bugs "reopen": Fixes are merged without explicit verification criteria, edge cases are missed, and regression tests aren't added.
This skill ensures:
Reproduction steps are verified BEFORE investigating
Fix Verification Criteria (FVC) are defined for every bug
Every fix must have a test that would have caught the bug
PR checklist maps to specific FVC
Input Handling
If no JIRA bug ID is provided, prompt the user to describe the bug manually:
Manual Investigation Mode: When no JIRA ticket exists, the investigation will:
Skip JIRA data fetching
Use the provided description for initial problem analysis
Create a manual bug ID based on description keywords
if [[ -f "$REPORT_FILE" ]]; thenecho"🔍 Found previous investigation for $BUG_ID"echo"📁 Location: $BUG_DIR"echo""# Show summary of previous findings
sed -n '/## Executive Summary/,/## Bug Details/p'"$REPORT_FILE" | head -20
sed -n '/## Root Cause Summary/,/## Code Analysis/p'"$REPORT_FILE" | head -20
LAST_MODIFIED=$(stat -f "%Sm" -t "%Y-%m-%d %H:%M""$REPORT_FILE" 2>/dev/null || \
date -r "$REPORT_FILE""+%Y-%m-%d %H:%M" 2>/dev/null || echo"Unknown")
echo"📅 Last Investigation: $LAST_MODIFIED"# Show outstanding action items
grep -A 10 "### Action Items""$REPORT_FILE" | grep "^- \[ \]" || trueecho""echo"Continue from previous findings (A) or start fresh (B)?"elseecho"🆕 No previous investigation found for $BUG_ID"echo"📁 Will create new investigation at: $BUG_DIR"fi
Do not proceed to deep investigation until FVC are defined.
Poor verification = bug "fixed" but reopens in a week.
Reproduction Verification
## Reproduction Confirmed### Environment- [ ] Browser/OS: [e.g., Chrome 120 on macOS]
- [ ] User role/permissions: [e.g., Admin user]
- [ ] Data state: [e.g., User with 3+ saved items]
### Steps to Reproduce1. [Exact step 1]
2. [Exact step 2]
3. [Exact step 3]
### Expected Result
[What should happen]
### Actual Result
[What actually happens — include error messages]
### Reproduction Rate- [ ] 100% reproducible
- [ ] Intermittent (X out of Y attempts)
- [ ] Environment-specific
Fix Verification Criteria (FVC)
## Fix Verification Criteria### Primary FVC (Must pass to close bug)
| ID | Criterion | Test Type | Verified |
| ----- | --------------------------------------- | ------------------ | -------- |
| FVC-1 | [Original bug scenario works correctly] | Manual + Automated | ⬜ |
| FVC-2 | [Edge case 1 works] | Automated | ⬜ |
| FVC-3 | [Edge case 2 works] | Automated | ⬜ |
### Regression FVC (Must not break)
| ID | Criterion | Test Exists | Verified |
| ------ | ----------------------------- | ----------- | -------- |
| FVC-R1 | [Related feature still works] | ⬜ | ⬜ |
| FVC-R2 | [Similar workflow unaffected] | ⬜ | ⬜ |
Edge Case Discovery
Scenario
Could This Also Fail?
Add to FVC?
Empty state
What if user has no data?
Large data
What if user has 1000+ items?
Concurrent users
What if two users do this simultaneously?
Slow network
What if request times out?
Partial data
What if some fields are null?
⚠️ CHECKPOINT — Before proceeding:
Bug is reproducible with documented steps
FVC are defined (at minimum: original scenario + 2 edge cases)
Regression areas identified
Test strategy is clear
4. Repository Investigation
Identify available repos
CURRENT_REPO=$(basename $(git rev-parse --show-toplevel 2>/dev/null) || echo"none")
echo"Current repository: $CURRENT_REPO"# Check for sibling repos (adjust paths for your project structure)# Common convention: repos sit side-by-side in the same parent directory
PARENT_DIR=$(dirname $(git rev-parse --show-toplevel 2>/dev/null))
echo"Sibling repos in $PARENT_DIR:"ls"$PARENT_DIR" 2>/dev/null | head -10
Investigation approaches
A. When working in a single repo:
Trace the bug within the current codebase
Search for the failing condition: git grep -n "relevant-pattern"
Question: Why wasn't this caught during development?
Review test coverage for the area
Check code review practices
Examine development guidelines
Why #5: Root Organizational Cause
Question: Why do our processes allow this?
Identify systemic issues
Review team practices and standards
Examine documentation and knowledge sharing
6. Evidence Collection
For each "Why", collect:
# Code snippets showing the issue
grep -rn "failing-pattern" src/
# Recent commits in the affected area
git log --oneline -20 -- path/to/affected/file
# Test coverage check# (varies by test framework — check package.json for the test command)
7. Generate Report
mkdir -p "$BUG_DIR"# Back up previous investigation if continuingif [[ -f "$REPORT_FILE" ]]; then
BACKUP_DIR="${BUG_DIR}/backups/$(date +%Y%m%d_%H%M%S)"mkdir -p "$BACKUP_DIR"cp"$REPORT_FILE""$BACKUP_DIR/investigation.md" 2>/dev/null || truecp"$TIMELINE_FILE""$BACKUP_DIR/timeline.md" 2>/dev/null || truecp"$RECOMMENDATIONS_FILE""$BACKUP_DIR/recommendations.md" 2>/dev/null || truefi
Generate three files:
investigation.md — main report:
# Bug Investigation: [BUG_ID]
**Bug:** [Summary]
**Date:** [Investigation Date]
**Severity:** [Priority]
**Status:** [Current Status]
---
## 🎯 FIX VERIFICATION CRITERIA
> **⚠️ Bug is NOT fixed until ALL FVC are verified.**
### Primary FVC
| ID | Criterion | Test Added | Verified |
| ----- | --------------------------- | ---------- | -------- |
| FVC-1 | Original bug scenario works | ⬜ | ⬜ |
| FVC-2 | [Edge case 1] | ⬜ | ⬜ |
| FVC-3 | [Edge case 2] | ⬜ | ⬜ |
### Regression FVC
| ID | Criterion | Test Exists | Verified |
| ------ | ----------------- | ----------- | -------- |
| FVC-R1 | [Related feature] | ⬜ | ⬜ |
---
## Executive Summary
### The Problem
[Clear description of what went wrong]
### Root Cause
[One sentence summary]
### Impact
- **Users Affected:** [Estimate]
- **Features Impacted:** [List]
## 5 Whys Analysis
### Why #1: Direct Cause
**Answer:** [Technical explanation]
**Evidence:**
```code
// Failing code
```
File: [path:line]
Error: [message]
Why #2: Process Failure
Answer: [Missing validation/checks]
Why #3: Design Issue
Answer: [Architectural limitations]
Why #4: Development Process Gap
Answer: [Process breakdown]
Why #5: Root Organizational Cause
Answer: [Systemic issue]
Root Cause Summary
Technical: [Specific technical issue]
Process: [Process or practice that failed]
Organizational: [Systemic issue to address]
Recommendations
Immediate Fix (P0)
[Specific fix with code snippet]
Short-term (P1)
Add tests: [test cases needed]
Improve validation: [where and what]
Long-term Prevention (P2)
Architecture change: [proposed improvement]
Process update: [new practice]
Action Items
Implement immediate fix
Write regression tests (must fail without fix, pass with fix)
Update documentation
Schedule architecture review if needed
**`timeline.md`** — chronological history of the bug from report to resolution.
**`recommendations.md`** — standalone doc with code-level improvement recommendations and process changes.
### 8. **Bug Fix PR Checklist**
Generate and share before merging the fix:
```markdown
# Bug Fix PR Checklist: [BUG_ID]
## 🎯 Fix Verification Criteria
| FVC ID | Criterion | Test Added | Manually Verified |
|--------|-----------|------------|-------------------|
| FVC-1 | [Original bug scenario] | ⬜ | ⬜ |
| FVC-2 | [Edge case 1] | ⬜ | ⬜ |
| FVC-3 | [Edge case 2] | ⬜ | ⬜ |
## Pre-Merge Checklist
- [ ] Fix addresses root cause (not just symptoms)
- [ ] Regression test added that would have caught this bug
- [ ] Test fails without fix, passes with fix
- [ ] Edge case tests added for FVC-2, FVC-3
- [ ] Related features still work (FVC-R1, FVC-R2)
- [ ] No new console errors
Notes:
REPORT_BASE defaults to $HOME/Documents/technical-analysis; override with env var
Requires jira CLI authenticated via jira init when using a ticket ID
When run without a ticket ID, enters manual description mode
FVC-first: verification criteria are defined before deep investigation begins
Every fix requires a regression test that would have caught the original bug
