| name | bug-investigation |
| description | 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
- Follow the same 5 Whys methodology
- Generate the same comprehensive documentation
Investigation Process:
0. Handle Input and Setup
if [[ -z "$ARGUMENTS" ]]; then
echo "🐛 No JIRA bug ID provided"
echo ""
echo "📝 Please describe the bug you're investigating:"
echo " - What is the issue/problem you're seeing?"
echo " - When did you first notice it?"
echo " - What steps reproduce the problem?"
echo " - What should happen vs what actually happens?"
echo " - Any error messages or symptoms?"
echo " - Which parts of the system seem affected?"
exit 0
fi
BUG_ID="$ARGUMENTS"
echo "🎯 Investigating bug: $BUG_ID"
REPORT_BASE="${REPORT_BASE:-$HOME/Documents/technical-analysis}"
BUG_DIR="${REPORT_BASE}/bugs/${BUG_ID}"
REPORT_FILE="${BUG_DIR}/investigation.md"
TIMELINE_FILE="${BUG_DIR}/timeline.md"
RECOMMENDATIONS_FILE="${BUG_DIR}/recommendations.md"
1. Check for Previous Investigation Findings
if [[ -f "$REPORT_FILE" ]]; then
echo "🔍 Found previous investigation for $BUG_ID"
echo "📁 Location: $BUG_DIR"
echo ""
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"
grep -A 10 "### Action Items" "$REPORT_FILE" | grep "^- \[ \]" || true
echo ""
echo "Continue from previous findings (A) or start fresh (B)?"
else
echo "🆕 No previous investigation found for $BUG_ID"
2. Fetch Bug Details from JIRA
jira issue view "$BUG_ID" --raw > /tmp/bug_details.json
SUMMARY=$(jq -r '.fields.summary' /tmp/bug_details.json)
DESCRIPTION=$(jq -r '.fields.description' /tmp/bug_details.json)
REPORTER=$(jq -r '.fields.reporter.displayName' /tmp/bug_details.json)
PRIORITY=$(jq -r '.fields.priority.name' /tmp/bug_details.json)
STATUS=$(jq -r '.fields.status.name' /tmp/bug_details.json)
COMPONENTS=$(jq -r '.fields.components[].name' /tmp/bug_details.json 2>/dev/null || echo "None")
LABELS=$(jq -r '.fields.labels[]' /tmp/bug_details.json 2>/dev/null || echo "None")
jira issue comment list "$BUG_ID" --raw > /tmp/bug_comments.json
echo "✅ Bug: $SUMMARY"
echo " Priority: $PRIORITY | Status: $STATUS"
3. Initial Problem Analysis
- Parse bug description and symptoms
- Identify affected components/features
- Determine when the issue started occurring
- Check for reproduction steps in the ticket
- Review any error messages or logs mentioned
- Determine if it's a frontend, backend, or integration issue
3.5 GATE: Define Fix Verification Criteria (FVC) ⚠️ CRITICAL
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 Reproduce
1. [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"
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"
- Check recent commits:
git log --oneline --since="2 weeks ago" --all
- Review git blame on suspicious files
B. When investigating across multiple repos:
- Identify the request/response boundary
- Trace the API call from client to server
- Check error contracts between systems
- Review deployment timelines for both repos
C. When source is unavailable:
- Work from JIRA comments, stack traces, and logs
- Document assumptions clearly in the report
5. 5 Whys Analysis
Why #1: Direct Cause
Question: Why did this bug occur?
- Find the specific code that failed
- Review error logs and stack traces
- Identify the failing condition or logic
- Check network requests/responses
Why #2: Process Failure
Question: Why did the code allow this to happen?
- Examine missing validation or error handling
- Check for missing guards or checks
- Review the code flow and logic paths
Why #3: Design/Architecture Issue
Question: Why was the system designed this way?
- Analyze architectural decisions
- Check for technical debt
- Examine coupling and dependencies
Why #4: Development Process Gap
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:
grep -rn "failing-pattern" src/
git log --oneline -20 -- path/to/affected/file
7. Generate Report
mkdir -p "$BUG_DIR"
if [[ -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 || true
cp "$TIMELINE_FILE" "$BACKUP_DIR/timeline.md" 2>/dev/null || true
cp "$RECOMMENDATIONS_FILE" "$BACKUP_DIR/recommendations.md" 2>/dev/null || true
fi
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
**`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
