┌─────────────────────────────────────────────────────────────────┐
│                 ISSUE RESOLUTION PIPELINE                       │
├─────────────────────────────────────────────────────────────────┤
│  Triage → Reproduce → RCA → Fix → Verify → Document             │
│     ↓         ↓        ↓     ↓      ↓         ↓                │
│  [CHECK]  [CHECK]  [CHECK] [DO]  [CHECK]   [DONE]              │
│                  ↑_________|                                    │
│                  (max 3 loops)                                  │
└─────────────────────────────────────────────────────────────────┘

🚨 ESCALATE TO USER when:
- Cannot reproduce after 30 minutes
- RCA inconclusive after 3 attempts  
- Fix introduces new test failures
- Issue requires architectural changes
- Touching code you don't understand

# Issue Brief: <Issue ID>

## Summary
<One-line description>

## Reported Behavior
<What the user sees/experiences>

## Expected Behavior
<What should happen>

## Impact
- **Severity**: Critical | High | Medium | Low
- **Affected Users**: <scope>
- **Affected Browsers**: Chrome | Firefox | Safari | All

## Error Information
- Console errors: <if any>
- Network errors: <if any>
- Stack trace: <if any>

## Initial Observations
- Recent changes: <commits/deploys>
- Related components: <React components>

## Classification
- **Type**: Bug | Regression | Performance | UI/UX | TypeScript
- **Area**: <component/feature>
- **Priority**: P0 | P1 | P2 | P3

═══════════════════════════════════════════════════════════
[CHECKPOINT: TRIAGE_COMPLETE]
═══════════════════════════════════════════════════════════

🐛 Issue: <summary>
📊 Severity: <level>
🎯 Area: <component>

Error: <error message if any>

Initial hypothesis:
• <hypothesis 1>
• <hypothesis 2>

👉 Proceed to reproduce? (yes/need-more-info)
═══════════════════════════════════════════════════════════

1. Open Chrome DevTools (F12)
2. Check Console tab for errors
3. Check Network tab for failed requests
4. Check React DevTools for component state
5. Check Application tab for localStorage/cookies

// Use mcp__playwright__browser_navigate
// Use mcp__playwright__browser_snapshot
// Use mcp__playwright__browser_console_messages

1. Read the error stack trace
2. Navigate to the source file
3. Add console.log at key points
4. Check component props and state

# Reproduction: <Issue ID>

## Environment
- Browser: <Chrome 120 / Firefox / Safari>
- OS: <Windows 11 / macOS>
- Screen: <Desktop / Mobile / Responsive>
- App Version: <version>

## Steps to Reproduce
1. Navigate to <URL>
2. <action>
3. <action>
4. → Error occurs

## Console Output

{
  "props": {},
  "state": {}
}

═══════════════════════════════════════════════════════════
[CHECKPOINT: REPRO_CONFIRMED]
═══════════════════════════════════════════════════════════

✅ Successfully reproduced!

Steps:
1. <step>
2. <step>
3. → Error: <error>

Console error:
<error message>

Reproduction rate: <X>%

👉 Proceed to Root Cause Analysis? (yes/no)
═══════════════════════════════════════════════════════════

═══════════════════════════════════════════════════════════
[CHECKPOINT: REPRO_FAILED]
═══════════════════════════════════════════════════════════

❌ Cannot reproduce after <N> attempts

Tried:
• <what you tried>
• <what you tried>

Need from you:
• Exact browser version?
• Any browser extensions?
• Network conditions?
• Screenshot/recording?

👉 Provide more details or skip to code analysis?
═══════════════════════════════════════════════════════════

1. Read error message carefully
2. Find the FIRST file in YOUR codebase (not node_modules)
3. Go to that line
4. Trace backwards to find the source

1. Check props being passed - are they correct?
2. Check state - is it what you expect?
3. Check useEffect dependencies - missing deps?
4. Check conditional rendering - wrong condition?
5. Check event handlers - correct binding?

User Action → Event Handler → State Update → Re-render → UI
     ↓              ↓              ↓            ↓        ↓
   Check         Check          Check        Check    Check

git bisect start
git bisect bad HEAD
git bisect good <last-known-good-commit>
# Test each commit
git bisect reset

1. Check request payload - sending correct data?
2. Check response - API returning expected shape?
3. Check error handling - catching API errors?
4. Check loading states - race conditions?

# Root Cause Analysis: <Issue ID>

## Investigation Path
| Step | Action | Finding |
|------|--------|---------|
| 1 | Read error trace | Points to ComponentX.tsx:42 |
| 2 | Check ComponentX | Props undefined |
| 3 | Check parent | Not passing required prop |
| 4 | Root cause found | ✅ |

## Root Cause
<Clear explanation of WHY the bug exists>

## Code Location
- **File**: `src/components/ComponentX.tsx`
- **Line(s)**: 42-45
- **Function**: `handleClick()`

## Why It Happened
```typescript
// ❌ Bug: Missing null check
const name = user.profile.name; // user.profile can be undefined

// ✅ Should be:
const name = user?.profile?.name ?? 'Guest';

**Checkpoint Output**:

---

### Phase 4: Fix
**Goal**: Implement the correction.

| Input | Output |
|-------|--------|
| rca.md | Code changes |

**Fix Guidelines**:
1. **Minimal change**: Fix only what's broken
2. **No scope creep**: Don't refactor unrelated code
3. **Type safety**: Ensure TypeScript is happy
4. **Add tests**: Prevent regression

**Frontend Fix Patterns**:

#### Pattern: Null/Undefined Safety
```typescript
// Before
const name = user.profile.name;

// After
const name = user?.profile?.name ?? 'Default';

// Before - stale closure
useEffect(() => {
  fetchData(userId);
}, []); // Missing userId

// After
useEffect(() => {
  fetchData(userId);
}, [userId]);

// Before
useEffect(() => {
  fetchData().then(setData);
}, []);

// After - with cleanup
useEffect(() => {
  let cancelled = false;
  fetchData().then(data => {
    if (!cancelled) setData(data);
  });
  return () => { cancelled = true; };
}, []);

// Before - recreates function every render
<Button onClick={() => handleClick(id)} />

// After - stable reference
const handleButtonClick = useCallback(() => {
  handleClick(id);
}, [id]);
<Button onClick={handleButtonClick} />

## Fix Implementation

### Changes Made
- [ ] `src/components/X.tsx`: <change description>
- [ ] `src/components/X.test.tsx`: Added regression test

### Verification Commands
- [ ] `yarn build` - No TypeScript errors
- [ ] `yarn lint` - No ESLint errors  
- [ ] `yarn test` - All tests pass

### Fix Type
- [ ] One-liner (simple fix)
- [ ] Small (< 20 lines changed)
- [ ] Medium (20-50 lines)
- [ ] Large (> 50 lines) ⚠️ Needs review

## Verification Checklist

### 1. Build Check
- [ ] `yarn build` passes
- [ ] No new TypeScript errors
- [ ] No new warnings

### 2. Test Check  
- [ ] Existing tests pass
- [ ] New regression test added
- [ ] New test passes

### 3. Manual Check
- [ ] Reproduce steps no longer trigger bug
- [ ] Related features still work
- [ ] No visual regressions

### 4. Browser Check (if UI change)
- [ ] Chrome ✅
- [ ] Firefox ✅
- [ ] Safari ✅ (if applicable)

### 5. Edge Cases
- [ ] Empty state handled
- [ ] Error state handled
- [ ] Loading state handled

Loop counter: <N>/3

❌ Verification failed: <reason>

Going back to RCA with new information:
• <what we learned>

───────────────────────────────────

═══════════════════════════════════════════════════════════
[CHECKPOINT: FIX_VERIFIED]
═══════════════════════════════════════════════════════════

✅ Fix Verified!

Changes:
• src/components/X.tsx (+5, -2)
• src/components/X.test.tsx (+15)

Verification:
✅ Build passes
✅ Tests pass (42 total, 1 new)
✅ Manual verification done

👉 Ready to document and close? (yes/more-testing)
═══════════════════════════════════════════════════════════

# Resolution: <Issue ID>

## Summary
<What was the bug and how was it fixed>

## Root Cause
<Brief explanation>

## Fix
```typescript
// Before
<problematic code>

// After  
<fixed code>

---

## Common Frontend Error Patterns

### React Errors

| Error | Cause | Fix |
|-------|-------|-----|
| `Cannot read property 'X' of undefined` | Missing null check | Optional chaining `?.` |
| `Maximum update depth exceeded` | useEffect infinite loop | Fix dependencies array |
| `Invalid hook call` | Hook outside component | Move hook inside component |
| `Each child should have unique key` | Missing/duplicate keys | Add unique keys |
| `Can't perform state update on unmounted` | Async after unmount | Add cleanup in useEffect |
| `Objects are not valid as React child` | Rendering object directly | Render specific property |

### TypeScript Errors

| Error | Cause | Fix |
|-------|-------|-----|
| `Type 'X' is not assignable to type 'Y'` | Type mismatch | Fix type or add assertion |
| `Property 'X' does not exist on type 'Y'` | Wrong type definition | Update interface |
| `Argument of type 'X' is not assignable` | Wrong function argument | Check function signature |
| `Object is possibly 'undefined'` | Missing null check | Add optional chaining |

### API/Network Errors

| Error | Cause | Fix |
|-------|-------|-----|
| `CORS error` | Backend CORS config | Fix backend or use proxy |
| `401 Unauthorized` | Token expired/missing | Refresh token or re-login |
| `404 Not Found` | Wrong endpoint | Check API URL |
| `500 Internal Server Error` | Backend bug | Check backend logs |
| `Network Error` | No connection | Add offline handling |

### State Management Errors

| Error | Cause | Fix |
|-------|-------|-----|
| Stale closure | Missing useCallback deps | Add all dependencies |
| State not updating | Mutating state directly | Use immutable update |
| Prop drilling issues | Deep component tree | Use Context or state lib |
| Re-render loop | State update in render | Move to useEffect |

---

## Tools to Use

| Tool | When to Use |
|------|-------------|
| **Read** | Examine source code |
| **Grep** | Find error patterns, usages |
| **finder** | Understand component relationships |
| **get_diagnostics** | Check TypeScript/ESLint errors |
| **Bash** | Run tests, build |
| **edit_file** | Apply fixes |
| **mcp__playwright__*** | Debug UI interactions |
| **mcp__playwright__browser_console_messages** | Get browser console errors |
| **mcp__playwright__browser_snapshot** | Capture page state |

---

## Quick Reference

| Phase | Action | Key Question | Max Time |
|-------|--------|--------------|----------|
| Triage | Categorize | What and how bad? | 10 min |
| Reproduce | Confirm | Can I trigger it? | 20 min |
| RCA | Investigate | Why does it happen? | 30 min |
| Fix | Implement | How to correct it? | 30 min |
| Verify | Confirm | Is it actually fixed? | 15 min |
| Document | Record | What did we learn? | 10 min |

---

## Anti-Patterns to Avoid

| ❌ Don't | ✅ Do Instead |
|----------|---------------|
| Random changes hoping to fix | Systematic RCA first |
| Suppress error without fixing | Fix the root cause |
| Refactor while fixing bug | Minimal targeted fix |
| Skip verification | Always test the fix |
| Forget regression test | Add test to prevent recurrence |
| Debug without console | Use DevTools extensively |
| Assume reproduction | Always reproduce first |
| Loop forever in RCA | Escalate after 3 attempts |