@tinkcarlos/skillora 0.2.0

package/.claude/skills/code-review/references/rca-techniques.md

@@ -0,0 +1,362 @@
+# Root Cause Analysis Techniques
+
+> Techniques for identifying the true source of bugs, not just symptoms.
+
+## Table of Contents
+
+- [RCA Principles](#rca-principles)
+- [RCA Techniques](#rca-techniques)
+  - [Five Whys](#1-five-whys)
+  - [Fishbone Diagram](#2-fishbone-diagram-ishikawa)
+  - [Timeline Analysis](#3-timeline-analysis)
+  - [Fault Tree Analysis](#4-fault-tree-analysis)
+  - [Change Analysis](#5-change-analysis)
+- [Code Path Tracing](#code-path-tracing)
+- [Root Cause Categories](#root-cause-categories)
+- [RCA Report Template](#rca-report-template)
+
+---
+
+## RCA Principles
+
+1. **Don't fix symptoms** — A fix that addresses symptoms will see the bug return
+2. **Ask "Why?" repeatedly** — Keep digging until you find the fundamental cause
+3. **Verify the cause** — Prove the root cause by showing the fix prevents the bug
+4. **Look for patterns** — Similar bugs may have the same root cause
+5. **Document for learning** — RCA helps prevent future similar bugs
+
+---
+
+## RCA Techniques
+
+### 1. Five Whys
+
+Start with the problem and ask "Why?" five times:
+
+```markdown
+**Problem**: Users receive duplicate emails
+
+**Why 1**: Why do users receive duplicate emails?
+→ Because the email service is called twice.
+
+**Why 2**: Why is the email service called twice?
+→ Because the submit handler fires twice.
+
+**Why 3**: Why does the submit handler fire twice?
+→ Because the button click event bubbles and triggers twice.
+
+**Why 4**: Why does the event bubble and trigger twice?
+→ Because there's no event.stopPropagation() or debouncing.
+
+**Why 5**: Why is there no prevention for double submission?
+→ Because the form component was written without considering rapid clicks.
+
+**Root Cause**: Form component lacks double-submission prevention.
+```
+
+### 2. Fishbone Diagram (Ishikawa)
+
+Categorize potential causes:
+
+```
+                    ┌─── People ──────┐
+                    │ - Training gap   │
+                    │ - Human error    │
+                    │                  │
+┌─── Process ──────┐│                  │┌─── Technology ────┐
+│ - Missing step   ││                  ││ - System bug       │
+│ - Wrong order    ││                  ││ - Integration issue│
+│ - No validation  ││      [BUG]       ││ - Performance      │
+└──────────────────┘│                  │└────────────────────┘
+                    │                  │
+┌─── Environment ──┐│                  │┌─── Data ────────────┐
+│ - Config diff    ││                  ││ - Invalid input      │
+│ - Network issue  ││                  ││ - Corrupted data     │
+│ - Resource limit │└──────────────────┘│ - Missing data       │
+└──────────────────┘                    └──────────────────────┘
+```
+
+### 3. Timeline Analysis
+
+For intermittent or timing-related bugs:
+
+```markdown
+## Timeline Analysis
+
+| Time | Event | System State | Notes |
+|------|-------|--------------|-------|
+| 00:00 | User clicks Submit | Form data valid | |
+| 00:01 | API call initiated | Loading state | |
+| 00:02 | User clicks Submit again | Already loading | No prevention! |
+| 00:03 | First API call completes | Success | |
+| 00:04 | Second API call completes | Duplicate! | |
+
+**Root Cause**: No loading state check before submit
+```
+
+### 4. Fault Tree Analysis
+
+Work backwards from the failure:
+
+```
+                    [Duplicate Email]
+                           │
+              ┌────────────┴────────────┐
+              │                         │
+    [Email sent twice]         [Two records created]
+              │                         │
+    ┌─────────┴─────────┐              │
+    │                   │              │
+[Double API call]  [Retry logic]  [Race condition]
+    │
+    │
+[No debounce on button]  ← ROOT CAUSE
+```
+
+### 5. Change Analysis
+
+Compare working vs broken states:
+
+```markdown
+## Change Analysis
+
+| Aspect | Working State | Broken State | Changed? |
+|--------|---------------|--------------|----------|
+| Code version | v1.2.3 | v1.2.4 | Yes ✓ |
+| Config | prod.yaml | prod.yaml | No |
+| Database | schema v42 | schema v42 | No |
+| Dependencies | package.json | package.json | No |
+| Environment | AWS us-east-1 | AWS us-east-1 | No |
+
+**Focus Investigation On**: Code changes in v1.2.4
+
+**Changed Files**:
+- src/services/email.ts (modified)
+- src/components/Form.tsx (modified) ← likely culprit
+
+**Root Cause**: Form.tsx change removed debounce logic
+```
+
+---
+
+## Code Path Tracing
+
+### Step 1: Identify Entry Point
+
+Where does the bug manifest?
+
+```
+Error message: "Cannot read property 'name' of undefined"
+Stack trace points to:
+src/components/UserProfile.tsx:23
+  const name = user.name; // Error here
+```
+
+### Step 2: Trace Data Flow
+
+Follow the data from source to error:
+
+```
+Entry: UserProfile.tsx:23 (user.name)
+   ↑
+   │ user comes from props
+   │
+Source: UserProfilePage.tsx:15
+   ↑
+   │ user comes from useUser hook
+   │
+Source: hooks/useUser.ts:8
+   ↑
+   │ user comes from API response
+   │
+Source: api/users.ts:12
+   ↑
+   │ API returns null when user not found
+   │
+ROOT CAUSE: No handling for API returning null
+```
+
+### Step 3: Document the Path
+
+```markdown
+## Code Path
+
+### Execution Flow
+1. UserProfilePage renders
+   └── Calls useUser(userId)
+       └── Fetches from /api/users/{id}
+           └── API returns null (user deleted)
+               └── useUser returns null
+                   └── UserProfile receives user=null
+                       └── Accesses user.name
+                           └── TypeError!
+
+### Missing Checks
+| Location | Should Check | Current |
+|----------|-------------|---------|
+| API response | user exists | No ❌ |
+| useUser hook | null handling | No ❌ |
+| UserProfile | user prop | No ❌ |
+
+### Fix Location Options
+1. API: Return 404 (proper REST) ← Best
+2. Hook: Return loading/error state
+3. Component: Null check before render
+```
+
+---
+
+## Root Cause Categories
+
+### Logic Errors
+
+```python
+# Bug: Off-by-one error
+for i in range(len(array) + 1):  # Should be len(array)
+    process(array[i])  # IndexError on last iteration
+
+# Bug: Wrong operator
+if user.role = 'admin':  # = should be ==
+    # Always assigns, doesn't compare
+
+# Bug: Incorrect condition
+if items.length > 0 or items.length < 10:  # or should be and
+    # Always true if length > 0
+```
+
+### Async/Timing Errors
+
+```python
+# Bug: Race condition
+data = None
+async def load_data():
+    global data
+    data = await fetch_data()
+
+load_data()  # Not awaited
+print(data)  # None - load_data hasn't finished
+
+# Bug: Unhandled promise/future rejection
+async def save():
+    await api.save(data)  # No try/except
+```
+
+### State Errors
+
+```python
+# Bug: Mutation of shared state
+items = []
+def add_item(item):
+    items.append(item)  # Mutates shared list!
+
+# Bug: Invalid state transition
+if status == 'pending':
+    status = 'complete'
+elif status == 'processing':
+    status = 'complete'  # Can go from processing to complete?
+```
+
+### Data Errors
+
+```python
+# Bug: Unexpected data type
+def format_date(date):
+    return date.isoformat()  # Fails if date is string
+
+# Bug: Missing data validation
+def create_user(data):
+    return {'email': data['email'].lower()}  # Fails if email is None
+
+# Bug: Data shape assumption
+def get_first_item(response):
+    return response['data']['items'][0]['name']  # Many assumptions!
+```
+
+### Integration Errors
+
+```python
+# Bug: API contract mismatch
+# Frontend expects: { user: { name: string } }
+# Backend returns: { data: { user: { name: string } } }
+name = response['user']['name']  # KeyError
+
+# Bug: Version mismatch
+# Library v1: response.json()
+# Library v2: response.body
+```
+
+---
+
+## RCA Report Template
+
+```markdown
+# Root Cause Analysis Report
+
+## Bug Summary
+| Field | Value |
+|-------|-------|
+| Bug ID | BUG-XXX |
+| Summary | [One line] |
+| Severity | Critical / High / Medium / Low |
+| Date Found | [Date] |
+| Date Fixed | [Date] |
+
+## Problem Statement
+[Detailed description of the bug]
+
+## Impact
+- Users affected: [Number/scope]
+- Features affected: [List]
+- Duration: [How long issue existed]
+
+## Root Cause
+
+### 5 Whys Analysis
+[Complete 5 whys]
+
+### Root Cause Statement
+**Category**: [Logic/Async/State/Data/Integration]
+
+**Description**: [Clear statement of root cause]
+
+**Code Location**: 
+- File: [path]
+- Line: [number]
+- Function: [name]
+
+## Fix
+
+### Solution
+[Description of fix]
+
+### Code Changes
+[Diff or description]
+
+### Why This Fix?
+[Justification]
+
+## Verification
+- [ ] Bug cannot be reproduced
+- [ ] Tests added for bug case
+- [ ] Related features verified
+
+## Similar Bug Hunt
+- [ ] Pattern extracted
+- [ ] Project-wide search completed
+- [ ] Similar instances fixed
+
+## Prevention
+
+### Immediate Actions
+- [Action 1]
+- [Action 2]
+
+### Long-term Improvements
+- [Improvement 1]
+- [Improvement 2]
+
+## Lessons Learned
+- [Lesson 1]
+- [Lesson 2]
+```
+