debug

Original source / Raw SKILL.md

---
name: debug
description: Fix bugs systematically instead of guessing. Use when features break, users report errors, or tests fail. Covers reproducing bugs, gathering diagnostic info, and working with AI tools to fix issues efficiently for non-technical founders.
---

# Debug

## Debugging Workflow

```
Debug Process:
- [ ] Reproduce bug consistently
- [ ] Capture what's happening (screenshots, errors)
- [ ] Check what changed recently
- [ ] Gather diagnostic info
- [ ] Give info to AI to diagnose
- [ ] AI proposes fix
- [ ] Test fix works
- [ ] Verify didn't break anything else
```

See [DEBUG-CHECKLIST.md](DEBUG-CHECKLIST.md) for detailed steps.

---

## The Golden Rule

**NO GUESSING. GATHER INFO FIRST.**

Bad approach:
1. Something broke
2. Try random fix
3. Doesn't work
4. Try another fix
5. Still broken after 5 attempts

Good approach:
1. Something broke
2. Reproduce it consistently
3. Gather diagnostic info
4. Give to AI to diagnose
5. AI fixes it (usually first try)

**Diagnosis before fixes.**

---

## Reproducing Bugs

**Before asking AI to fix, reproduce it:**

```
Can you reproduce it?
- [ ] Exact steps to trigger bug
- [ ] Happens every time
- [ ] Happens on specific browser/device
- [ ] Happens with specific data

If can't reproduce:
- Ask user for exact steps
- Try different browser/device
- Try with different data
- Check if intermittent (timing issue)
```

**Tell AI:**
```
Bug: [description]

Steps to reproduce:
1. [Step]
2. [Step]
3. [Bug happens]

Happens: [Always / Sometimes / Once]
Browser: [Chrome 120 on Mac]
Screenshot: [attach]
```

---

## Capturing Error Info

### Browser Console Errors

**Open console:**
1. Right-click page → Inspect
2. Click "Console" tab
3. Look for red errors

**Screenshot errors and give to AI:**
```
I see this error in console:
[paste error message]

When it happens:
[what you were doing]

Please:
1. Explain what this means
2. Identify the cause
3. Fix the issue
```

### Network Errors

**Check network tab:**
1. Open DevTools → Network
2. Reproduce bug
3. Look for failed requests (red)
4. Click failed request
5. Check response

**Tell AI:**
```
API call failing:
URL: /api/endpoint
Status: 500 Internal Server Error
Response: [paste error response]

This happens when: [action]
```

### Visual Bugs

**Screenshot everything:**
- What you expected to see
- What actually shows
- Full page context
- Error messages

**Tell AI:**
```
Visual bug: [description]
Expected: [screenshot or description]
Actual: [screenshot]
Device: [iPhone 14, Chrome on Mac, etc]
```

---

## What Changed?

**Ask yourself:**
- Did this work yesterday?
- What did AI change today?
- Did you deploy recently?
- Did you change any settings?

**Tell AI:**
```
This worked yesterday, broke today.
Changes made today:
- [Change 1]
- [Change 2]

Which could cause: [the bug]?
```

---

## Common Bug Types

### "Nothing happens when I click"

**Check:**
- Console errors?
- Network request failing?
- Button actually clickable?

**Tell AI:**
```
Button does nothing when clicked.
Button: [which button]
Expected: [what should happen]
Console errors: [paste any errors]
```

### "Page won't load"

**Check:**
- Network errors?
- JavaScript errors?
- Infinite redirect?

**Tell AI:**
```
Page won't load: /page/url
Browser shows: [blank / error / loading forever]
Console errors: [paste]
Network errors: [paste]
```

### "Wrong data showing"

**Check:**
- API returning wrong data?
- Caching issue?
- State management bug?

**Tell AI:**
```
Showing wrong data.
Expected: [User A's profile]
Showing: [User B's profile]
API response: [paste from Network tab]
```

### "Form doesn't submit"

**Check:**
- Validation errors?
- Console errors?
- Network request happening?

**Tell AI:**
```
Form won't submit.
Form: [which form]
Filled: [what data entered]
Validation errors: [any visible]
Console errors: [paste]
```

---

## Working with AI to Debug

### Step 1: Gather Info

```
Before asking AI to fix, provide:
- Exact steps to reproduce
- Expected vs actual behavior
- Screenshots/error messages
- Browser and device
- What changed recently (if known)
```

### Step 2: AI Diagnoses

```
[Paste all info above]

Before proposing fixes:
1. What do you think is wrong?
2. Why is it happening?
3. What needs to change?

Explain in plain English first.
```

### Step 3: AI Fixes

```
Okay, now please fix it.

After fixing:
- Explain what you changed
- How to test the fix
- What to watch out for
```

### Step 4: Verify Fix

```
Test the fix:
- [ ] Original bug is gone
- [ ] Tested same steps, works now
- [ ] Related features still work
- [ ] No new console errors
```

See [DEBUG-PROMPTS.md](DEBUG-PROMPTS.md) for more patterns.

---

## When You're Stuck

**After 2 failed fix attempts:**

Stop. Don't try a 3rd fix.

**Ask AI:**
```
Tried 2 fixes, both didn't work.

Original bug: [description]
Fix 1: [what we tried] - didn't work
Fix 2: [what we tried] - still broken

Questions:
- Are we fixing the wrong thing?
- Is there a better approach?
- Should we start over?
```

**If 3+ fixes failed:** Probably need to rethink approach, not try more fixes.

---

## Intermittent Bugs

**"It works sometimes, breaks sometimes"**

**Likely causes:**
- Race condition (timing)
- Caching issue
- Network timing
- External API flakiness

**Tell AI:**
```
Bug is intermittent.
Works: [X] out of 10 times
Fails: [Y] out of 10 times

Pattern noticed:
- Fails more often when [condition]
- Never fails when [condition]

Please add logging to capture when it fails.
```

---

## Bugs in Production

**Users reporting bugs in live app:**

**Priority 1: Can users work around it?**
- Yes → Fix in next deployment
- No → Emergency fix needed

**For emergency fixes:**
```
Production bug blocking users.
Bug: [description]
Impact: [how many users affected]

Need quick fix:
- Simplest solution that works
- Don't optimize, just unblock users
- Can improve later
```

**For non-urgent:**
```
Production bug reported by user.
Bug: [description]
Impact: [minor / major]
Can work around: [yes / no]

Reproduce in development:
[steps]

Then fix and test before deploying.
```

---

## Reading Error Messages

**Common error patterns:**

**"Cannot read property of undefined"**
- Trying to access something that doesn't exist
- Check: Is data loaded before accessing it?

**"Maximum call stack exceeded"**
- Infinite loop or recursion
- Check: Function calling itself forever?

**"Network request failed"**
- API call not working
- Check: Network tab for status code

**"Unauthorized" or "401"**
- Authentication issue
- Check: Are you logged in? Token valid?

**"Internal Server Error" or "500"**
- Backend problem
- Check: Server logs for details

See [ERROR-MESSAGES.md](ERROR-MESSAGES.md) for more.

---

## Debugging Tools

**Built into browser:**
- Console: See errors and logs
- Network: See API calls and responses
- Elements: Inspect HTML/CSS
- Sources: Set breakpoints (advanced)

**How to use:**
1. Open DevTools (F12 or right-click → Inspect)
2. Click relevant tab
3. Reproduce bug
4. Look for errors/failed requests

**Screenshot and give to AI** - AI can interpret errors.

---

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Trying fixes without info | Gather diagnostic info first |
| "It doesn't work" | Be specific: what doesn't work? |
| Not reproducing first | Find consistent steps to trigger bug |
| Random fixes | Diagnose root cause first |
| Ignoring console errors | Always check console |
| Not testing after fix | Verify fix works, didn't break other things |

---

## When to Get Help

**Consider hiring developer when:**
- Stuck after following this process
- Critical bug can't figure out
- Same bug keeps coming back
- Bug in complex integration
- Need production fixed urgently

**For most bugs:** Following this process with AI is sufficient.

---

## Prevention

**After fixing, ask AI:**
```
Bug is fixed. 

How could we have prevented this?
- Better validation?
- Better error handling?
- Testing we should add?
```

**Build prevention into next features.**

---

## Quick Debug Checklist

**When something breaks:**

```
Quick Debug:
- [ ] Can I reproduce it?
- [ ] Any console errors?
- [ ] Any network errors?
- [ ] What changed recently?
- [ ] Screenshot the issue
- [ ] Gather all info
- [ ] Give to AI with context
- [ ] Test AI's fix
```

**5 minutes of diagnosis > 2 hours of guessing**

---

## Success Looks Like

✅ Bugs fixed on first or second try  
✅ Can explain what was wrong  
✅ Know how to reproduce bugs  
✅ Gather complete info before asking for fixes  
✅ Verify fixes work and don't break other things  
✅ Bugs getting rarer over time (learning patterns)

---

## Referenced Files

> The following files are referenced in this skill and included for context.

### DEBUG-CHECKLIST.md

```markdown
# Debug Checklist

Systematic steps for debugging any issue.

---

## Phase 1: Reproduce

### Make It Happen Consistently

```
Reproduction Steps:
1. What exact actions trigger the bug?
2. Does it happen every time?
3. Does it happen on all browsers?
4. Does it happen with all data?
5. Does it happen for all users?
```

### Document Steps

```
Bug Report:
Title: [Short description]
Steps:
1. [Action]
2. [Action]
3. [Bug occurs]

Expected: [What should happen]
Actual: [What actually happens]
Frequency: [Always / 80% / Rare]
```

### If Can't Reproduce

```
Try:
- Different browser (Chrome, Safari, Firefox)
- Different device (phone, desktop)
- Different account/user
- Different data/inputs
- Clear cache and try again

Still can't reproduce?
- Ask user for more details
- Screen recording from user
- Might be environmental (network, etc)
```

---

## Phase 2: Gather Evidence

### Check Console

```
1. Open DevTools (F12)
2. Click "Console" tab
3. Reproduce bug
4. Look for:
   - Red errors (critical)
   - Yellow warnings (important)
   - Failed network requests
```

**Screenshot and save:**
- Full error message
- Stack trace (if any)
- Context (what you were doing)

### Check Network

```
1. DevTools → Network tab
2. Reproduce bug
3. Look for:
   - Failed requests (red, 4xx, 5xx)
   - Slow requests (>1 second)
   - Missing requests (expected call didn't happen)
```

**For failed requests:**
- Click failed request
- Check "Response" tab
- Screenshot error response
- Note request URL and method

### Check What Changed

```
Review recent changes:
- Git commits today
- Features deployed recently
- Settings changed
- Dependencies updated

Ask: What's different from when it worked?
```

---

## Phase 3: Diagnose with AI

### Give Complete Context

```
Provide to AI:

Bug: [description]

Steps to reproduce:
1. [Step]
2. [Step]
3. [Bug happens]

Evidence:
- Console error: [paste]
- Network error: [paste]
- Screenshot: [attach]

Environment:
- Browser: [Chrome 120]
- Device: [MacBook Pro]
- URL: [where it happened]

Recent changes:
- [What changed recently]

Before proposing fixes:
1. What's the root cause?
2. Why is it happening?
3. What needs to change?
```

### Ask for Explanation First

```
Don't jump to fixes.

Ask AI:
- What's actually wrong?
- Why is this happening?
- Is this the real problem or symptom?

Understand before fixing.
```

---

## Phase 4: Fix and Verify

### AI Proposes Fix

```
After AI proposes fix:

Questions to ask:
- Will this fix the root cause?
- Could this break anything else?
- How do I test that it worked?

If unclear, ask AI to explain more.
```

### Test the Fix

```
Testing checklist:
- [ ] Reproduce original bug (should be gone)
- [ ] Test happy path (still works)
- [ ] Test related features (no regression)
- [ ] Check console (no new errors)
- [ ] Test in multiple browsers
- [ ] Test on mobile
```

### Verify No Regression

```
After fix, test:
- Feature that was broken (now works)
- Related features (still work)
- Unrelated features (quick check)

If anything broke:
"Fix worked but broke [X]. Need to adjust."
```

---

## Common Debug Patterns

### Pattern 1: It Worked, Now Broken

**Diagnosis:**
- What changed between working and broken?
- Deployment? Code change? Setting change?

**Action:**
```
Tell AI:
"Worked yesterday, broke today.
Changes made: [list changes]
Which could cause: [the bug]?"
```

### Pattern 2: Works Sometimes

**Diagnosis:**
- Timing issue?
- Race condition?
- Caching?
- External API flaky?

**Action:**
```
Tell AI:
"Intermittent bug.
Works: [X%] of time
Pattern: [when it fails more/less]
Need logging to capture failures."
```

### Pattern 3: Works in Dev, Broken in Production

**Diagnosis:**
- Environment differences?
- Missing env variables?
- Different data?
- Different traffic/load?

**Action:**
```
Tell AI:
"Works locally, fails in production.
Production error: [error]
Check environment config and deployment."
```

### Pattern 4: Works in Chrome, Broken in Safari

**Diagnosis:**
- Browser compatibility issue
- CSS/JS not supported
- Different default behaviors

**Action:**
```
Tell AI:
"Works in Chrome, broken in Safari.
Safari error: [error or description]
Fix browser compatibility."
```

---

## Debugging Edge Cases

### Empty State Bugs

```
Test with:
- No data at all
- Empty lists
- Missing fields

Common issues:
- "Cannot read property" errors
- Blank pages
- Broken layouts
```

### Data Volume Bugs

```
Test with:
- 1 item
- 100 items
- 10,000 items

Common issues:
- Slow performance
- Crashes
- UI breaks
```

### Timing Bugs

```
Test:
- Slow connection (3G)
- Fast actions (double-click)
- Let session expire
- Multiple tabs

Common issues:
- Race conditions
- Stale data
- Session issues
```

---

## Multi-Issue Debugging

### One Bug or Many?

**Symptoms that look like one bug might be:**
- Multiple small issues
- One root cause with many symptoms

**Approach:**
```
List all symptoms:
1. [Symptom]
2. [Symptom]
3. [Symptom]

Ask AI:
"Are these separate bugs or one root cause?"
```

### Priority Order

```
Fix in order:
1. Blocking bugs (can't use app)
2. Critical bugs (main features broken)
3. Major bugs (important features broken)
4. Minor bugs (edge cases)

Don't fix minor while critical unfixed.
```

---

## When Stuck

### After 1 Failed Fix

```
Reassess:
- Did we misdiagnose?
- Is there more info needed?
- Try different approach?

Tell AI:
"Fix didn't work. Here's what happened: [new info]"
```

### After 2 Failed Fixes

```
Stop trying fixes.

Tell AI:
"2 fixes failed. 
Fix 1: [tried] → [result]
Fix 2: [tried] → [result]

Are we fixing wrong thing?
Should we rethink approach?"
```

### After 3 Failed Fixes

```
Don't try 4th fix.

Options:
1. Start feature over with better approach
2. Get human developer help
3. Work around the bug temporarily

Tell AI:
"3 fixes failed. This approach isn't working.
Should we rebuild this differently?"
```

---

## Logging for Debugging

### Add Strategic Logs

```
Tell AI:
"Add logging to help debug:
- Log when [event] happens
- Log [variable] values
- Log API request/response
- Log errors with context"
```

### Useful Log Points

```
Log at:
- Function entry/exit
- Before/after API calls
- When changing state
- In error handlers
- At decision points
```

### Log Format

```
Good log:
[TIMESTAMP] [LEVEL] [CONTEXT] Message

Example:
[2025-01-13 10:30:45] [ERROR] [UserAuth] 
Login failed for user: [email protected]
Reason: Invalid password
Attempts: 3
```

---

## Documentation

### Bug Fix Log

```
Keep simple log:

Date: 2025-01-13
Bug: Form submission fails
Root cause: Missing validation
Fix: Added client-side validation
Tested: Chrome, Safari, mobile
Prevention: Add validation to all forms
```

### Known Issues

```
Track unfixed bugs:

Bug: Dashboard slow with 1000+ items
Workaround: Pagination added
Permanent fix: TODO - optimize query
Priority: Medium
```

---

## Prevention

### After Every Bug Fix

```
Ask:
- How could we have caught this earlier?
- What test would have found this?
- What validation would prevent this?

Tell AI:
"Bug fixed. How do we prevent similar bugs?"
```

### Common Prevention

```
Prevent by:
- Input validation
- Error boundaries
- Type checking
- Better error messages
- Loading states
- Edge case testing
```

---

## Quick Reference

**5-Minute Debug:**
```
1. Reproduce bug
2. Check console errors
3. Check network errors
4. Screenshot everything
5. Give to AI with context
```

**15-Minute Debug:**
```
1. Reproduce consistently
2. Gather all diagnostic info
3. Check what changed
4. AI diagnoses root cause
5. AI fixes
6. Test fix + verify no regression
```

**When to escalate:**
```
- After 2-3 failed fix attempts
- Critical production bug
- Can't reproduce at all
- Security issue
- Data corruption risk
```
```

### DEBUG-PROMPTS.md

```markdown
# Debug Prompts for AI

Effective prompts for debugging with AI tools.

---

## Initial Bug Report

```
Bug found: [Short description]

Steps to reproduce:
1. [Action]
2. [Action]
3. [Bug happens]

Expected: [What should happen]
Actual: [What happens]

Evidence:
- Console error: [paste or screenshot]
- Network error: [paste response]
- Screenshot: [attach]

Environment:
- Browser: [Chrome 120 on Mac]
- Device: [Desktop / iPhone 14]
- URL: [where it occurred]

Recent changes:
- [Anything changed recently?]

Before proposing fixes, please:
1. Explain what you think is wrong
2. Why it's happening
3. What needs to change
```

---

## Asking AI to Diagnose

```
[Paste bug report above]

Before fixing, help me understand:
- What's the root cause?
- Why is this happening?
- Is this the real problem or a symptom?
- Are there related issues?

Explain in plain English first.
```

---

## Reproduction Issues

```
Users report: [bug description]

But I can't reproduce it.

Tried:
- [Browsers tested]
- [Devices tested]
- [Steps tried]

Can you help identify:
- What conditions might trigger this?
- What should I test that I haven't?
- How to make it happen consistently?
```

---

## Intermittent Bugs

```
Bug happens sometimes, not always.

Frequency: Works [X] times, fails [Y] times out of 10

Pattern noticed:
- Fails more when: [condition]
- Never fails when: [condition]
- Sometimes happens after: [event]

Please:
1. Add detailed logging to capture when it fails
2. Log relevant state before/after
3. Help identify timing or condition that triggers it
```

---

## Console Error Diagnosis

```
Getting this error in console:
[Paste full error message and stack trace]

When: [What action triggers it]
Frequency: [Always / Sometimes]
Browser: [Which browser]

Questions:
- What does this error mean in plain English?
- What's the likely cause?
- How serious is it?
- How do we fix it?
```

---

## Network Error Diagnosis

```
API call failing:

Request:
- URL: /api/endpoint
- Method: POST
- Body: [paste request body]

Response:
- Status: 500
- Body: [paste error response]

When: [What triggers this call]
Context: [What user was doing]

Questions:
- What went wrong on the server?
- Is this a frontend or backend issue?
- How do we fix it?
```

---

## Visual Bug Diagnosis

```
Visual bug on [page/component]:

Expected: [Screenshot or description]
Actual: [Screenshot showing problem]

Occurs on:
- Device: [Desktop / iPhone 14]
- Browser: [Chrome / Safari]
- Screen size: [Specific size if known]

Doesn't occur on:
- [Where it works correctly]

Please:
1. Identify what's causing the layout issue
2. Propose CSS fix
3. Ensure fix works on all screen sizes
```

---

## "Nothing Happens" Bugs

```
Bug: Clicking [button/link] does nothing

Expected: [What should happen]
Actual: Nothing (no error, no action)

Checked:
- Console: [Any errors? Paste if yes]
- Network: [Any request made? Paste if yes]
- Button state: [Enabled/disabled]

The button appears clickable but nothing happens.
What could cause this?
```

---

## "Wrong Data" Bugs

```
Bug: Showing wrong data

Expected: [User A's data / Specific data]
Showing: [User B's data / Wrong data]

Context:
- User ID: [If relevant]
- Page: [Where showing wrong data]
- Data source: [API endpoint if known]

API Response (from Network tab):
[Paste response]

Questions:
- Is API returning wrong data?
- Is frontend displaying wrong data?
- Is there a caching issue?
```

---

## Fix Didn't Work

```
Tried fixing but issue persists.

Original bug: [Description]

Fix attempted:
[What we changed]

Result:
[What happened - still broken? Different error?]

New information:
- Console now shows: [Any new errors]
- Behavior changed to: [How it's different]

Questions:
- Did we fix the wrong thing?
- Is there a different root cause?
- Should we try different approach?
```

---

## Multiple Failed Fixes

```
Stuck on this bug after [2/3] fix attempts.

Original problem:
[Description]

Fix 1: [What we tried]
Result: [Didn't work / Made it worse]

Fix 2: [What we tried]
Result: [Still broken]

Questions:
- Are we approaching this wrong?
- Should we start over?
- Is there a simpler solution?
- What are we missing?
```

---

## Edge Case Investigation

```
Bug only happens in specific situation:

Works when:
- [Conditions where it works]

Fails when:
- [Conditions where it fails]

Specific trigger:
[Exact condition that causes failure]

This seems like an edge case.
How do we handle this scenario properly?
```

---

## Performance Bug

```
[Feature/Page] is very slow.

Observed performance:
- Takes: [X] seconds
- Should take: [Y] seconds

When measured:
- Action: [What's slow]
- Device: [Type]
- Network: [Fast / 3G]

What I checked:
- Network tab: [Any slow requests?]
- Console: [Any warnings?]
- Happens: [Always / Sometimes]

What's causing the slowdown?
```

---

## After User Report

```
User reported issue but can't reproduce.

User's report:
"[Exact words from user]"

User context:
- When: [Date/time]
- Where: [Page/feature]
- Device: [If known]
- Browser: [If known]

Monitoring shows:
- Errors at that time: [Check Sentry]
- Logs at that time: [Check logs]

Can you help interpret what happened?
```

---

## Security-Related Bug

```
Potential security issue:

What happened:
[Description of unexpected behavior]

Concern:
[Why this might be security issue]

Evidence:
- [What you observed]
- [Screenshots/logs]

Questions:
- Is this a real security issue?
- How serious?
- What's the proper fix?
- What else should we check?

Please prioritize security in your response.
```

---

## Regression Bug

```
This worked before, broke after recent change.

What broke:
[Feature/functionality]

When it broke:
[After which deploy/change]

Recent changes:
[List changes from that deploy]

Error:
[If any error, paste it]

Please:
1. Identify which change caused regression
2. How to fix without breaking new feature
3. How to prevent similar regressions
```

---

## Database-Related Bug

```
Issue seems database-related:

Symptom:
[What's happening]

Error (if any):
[Database error message]

When:
[What action triggers it]

Database context:
- Type: [PostgreSQL/MySQL/etc]
- Query: [If known]
- Data size: [How much data]

Questions:
- Is this a query problem?
- Is this a data problem?
- How do we fix it safely?
```

---

## Integration Bug

```
Issue with [Third-party service] integration:

Service: [Stripe/SendGrid/etc]
Issue: [What's not working]

Error from service:
[Paste error message/response]

Our code:
[Relevant code snippet if short]

Service dashboard shows:
[What you see in their dashboard]

Questions:
- Is this our bug or their bug?
- Are we calling API correctly?
- How do we fix this?
```

---

## Mobile-Specific Bug

```
Bug only on mobile:

Works on:
- Desktop Chrome
- Desktop Safari

Fails on:
- [iPhone/Android]
- [Browser]

Error:
[Mobile console error if available]

Behavior:
[Describe what happens on mobile]

Screenshots:
[Mobile screenshots]

How do we fix for mobile without breaking desktop?
```

---

## Testing Fix Request

```
Bug is fixed (we think).

Original bug: [Description]
Fix applied: [What we changed]

Before deploying, please:
1. Verify this fixes the root cause
2. Check if this could break anything else
3. Suggest how to test the fix
4. Identify any edge cases to test
```

---

## Prevention Analysis

```
Bug is fixed and deployed.

Original bug: [What happened]
Root cause: [Why it happened]
Fix: [How we fixed it]

Questions:
- How could we have prevented this?
- What validation should we add?
- What monitoring should we add?
- What tests should we write?

Help me prevent similar bugs in the future.
```

---

## Quick Debug Prompts

**Fast diagnosis:**
```
Quick debug needed:
- Bug: [One sentence]
- Error: [Paste error]
- When: [One sentence]

What's wrong and how to fix?
```

**Is this serious:**
```
Got this error: [Paste error]

Questions:
- How serious? (Critical/Important/Minor)
- Needs immediate fix?
- Impact on users?
```

**Better error messages:**
```
Error message says: "[Current message]"

This is confusing to users.

Please:
1. Change to user-friendly message
2. Add helpful instructions
3. Log technical details separately
```
```

### ERROR-MESSAGES.md

```markdown
# Common Error Messages

What errors mean and how to fix them.

---

## JavaScript Errors

### "Cannot read property 'X' of undefined"

**What it means:**
Trying to access property of something that doesn't exist.

**Example:**
```javascript
user.profile.name  // Error if user.profile is undefined
```

**Common causes:**
- Data not loaded yet
- API returned null
- Typo in property name
- Wrong data structure

**Fix:**
```
Add checks before accessing:
- if (user?.profile?.name)
- Optional chaining (?.)
- Load data before rendering
```

### "Cannot read property 'X' of null"

**What it means:**
Similar to undefined, but explicitly null.

**Common causes:**
- Database returned null
- User not found
- Data deleted
- Form field empty

**Fix:**
```
Check for null before using:
- if (data !== null)
- Provide default values
- Handle empty states
```

### "Maximum call stack size exceeded"

**What it means:**
Infinite loop or recursion.

**Common causes:**
- Function calls itself forever
- Circular reference
- State update triggers itself

**Fix:**
```
Find the loop:
- Check recursive functions
- Check useEffect dependencies
- Check state update logic
- Add base case to recursion
```

### "Unexpected token"

**What it means:**
Syntax error in code.

**Common causes:**
- Missing comma or bracket
- Typo in code
- Wrong quotes
- Copy-paste error

**Fix:**
```
Check syntax:
- Match all brackets { [ (
- Check commas in objects/arrays
- Verify quotes match
- Use linter/formatter
```

---

## Network Errors

### "Failed to fetch" / "Network request failed"

**What it means:**
Couldn't connect to API.

**Common causes:**
- No internet connection
- API server down
- CORS issue
- Wrong URL

**Fix:**
```
Check:
- Is API running?
- Is URL correct?
- Is CORS configured?
- Add error handling for offline
```

### "401 Unauthorized"

**What it means:**
Not authenticated.

**Common causes:**
- Not logged in
- Token expired
- Token invalid
- Wrong token sent

**Fix:**
```
Check authentication:
- Is user logged in?
- Is token in request?
- Is token expired?
- Redirect to login if needed
```

### "403 Forbidden"

**What it means:**
Authenticated but not allowed.

**Common causes:**
- Wrong permissions
- Try to access other user's data
- Try to access admin route
- Account suspended

**Fix:**
```
Check authorization:
- Does user have permission?
- Check user role
- Check resource ownership
- Show proper error message
```

### "404 Not Found"

**What it means:**
Resource doesn't exist.

**Common causes:**
- Wrong URL
- Item deleted
- ID doesn't exist
- Route not defined

**Fix:**
```
Handle gracefully:
- Show "Not found" page
- Check if URL correct
- Verify ID exists
- Redirect to valid page
```

### "429 Too Many Requests"

**What it means:**
Rate limit exceeded.

**Common causes:**
- Too many API calls
- Rapid clicking
- No debouncing
- Loop making requests

**Fix:**
```
Reduce requests:
- Add debouncing
- Disable button after click
- Cache responses
- Batch requests
- Wait before retry
```

### "500 Internal Server Error"

**What it means:**
Server crashed or has bug.

**Common causes:**
- Backend code error
- Database connection lost
- Uncaught exception
- Resource exhausted

**Fix:**
```
Check server:
- Look at server logs
- Check recent deploys
- Verify database connection
- Check resource usage
- Rollback if needed
```

### "502 Bad Gateway" / "503 Service Unavailable"

**What it means:**
Service temporarily down.

**Common causes:**
- Server restarting
- Deployment happening
- Too much traffic
- Database down

**Fix:**
```
Usually temporary:
- Wait and retry
- Check hosting status
- Check if deploying
- Scale up if needed
```

### "504 Gateway Timeout"

**What it means:**
Request took too long.

**Common causes:**
- Slow database query
- Slow external API
- Processing too much data
- Server overloaded

**Fix:**
```
Speed up request:
- Optimize queries
- Add timeout handling
- Process asynchronously
- Add loading state
```

---

## React Errors

### "Cannot update component while rendering different component"

**What it means:**
State update during render.

**Common causes:**
- setState in render function
- setState in useEffect without deps
- Prop function calls setState

**Fix:**
```
Move state updates:
- Into useEffect
- Into event handlers
- Add dependency array
- Don't call during render
```

### "Too many re-renders"

**What it means:**
Infinite render loop.

**Common causes:**
- setState in render
- useEffect missing dependencies
- Function recreated every render

**Fix:**
```
Break the loop:
- Add useEffect dependency array
- Use useCallback for functions
- Don't setState in render
- Check infinite loops
```

### "A component is changing uncontrolled input to controlled"

**What it means:**
Input value switching between undefined and defined.

**Common causes:**
- Initial value is undefined
- Switching between null and string
- Conditional value attribute

**Fix:**
```
Always provide value:
- Default to empty string: value={data || ""}
- Don't switch between value and no value
- Initialize state properly
```

---

## Database Errors

### "Connection timeout"

**What it means:**
Can't connect to database.

**Common causes:**
- Database down
- Wrong connection string
- Network issue
- Firewall blocking

**Fix:**
```
Check connection:
- Verify database running
- Check connection string
- Check network access
- Increase timeout if needed
```

### "Deadlock detected"

**What it means:**
Two operations waiting on each other.

**Common causes:**
- Concurrent updates
- Transaction lock issues
- Complex queries

**Fix:**
```
Prevent deadlocks:
- Retry failed queries
- Simplify transactions
- Lock in consistent order
- Reduce transaction time
```

### "Duplicate entry" / "Unique constraint violation"

**What it means:**
Trying to insert duplicate unique value.

**Common causes:**
- Email already exists
- Username taken
- ID collision
- Double-submit

**Fix:**
```
Handle gracefully:
- Check existence before insert
- Catch error and show message
- Use UPDATE instead of INSERT
- Prevent double-submit
```

---

## Authentication Errors

### "Invalid token" / "Token expired"

**What it means:**
JWT token is invalid or old.

**Common causes:**
- Session expired
- Token manually modified
- Server secret changed
- Clock skew

**Fix:**
```
Handle token issues:
- Redirect to login
- Clear invalid token
- Refresh token if possible
- Show clear message
```

### "Password incorrect"

**What it means:**
Wrong password entered.

**Common causes:**
- User typo
- Caps lock on
- Wrong account
- Password changed

**Fix:**
```
Help user:
- Show "Invalid email or password"
- Don't specify which is wrong
- Add "Forgot password" link
- Limit attempts
```

---

## Payment Errors

### "Card declined"

**What it means:**
Payment method rejected.

**Common causes:**
- Insufficient funds
- Card expired
- Card blocked
- Wrong card details

**Fix:**
```
Guide user:
- Show clear error from Stripe
- Suggest trying different card
- Don't store card details
- Log for support
```

### "Payment method required"

**What it means:**
No payment method attached.

**Common causes:**
- Card not added
- Card expired
- Card removed
- Setup incomplete

**Fix:**
```
Fix workflow:
- Prompt to add card
- Guide through setup
- Verify card before checkout
- Show clear instructions
```

---

## Browser Errors

### "Not enough memory"

**What it means:**
Page using too much RAM.

**Common causes:**
- Memory leak
- Too much data loaded
- Large images
- Not cleaning up

**Fix:**
```
Reduce memory:
- Paginate data
- Lazy load images
- Clean up event listeners
- Optimize bundle size
```

### "Script error"

**What it means:**
Generic error from CDN/external script.

**Common causes:**
- CORS blocking details
- Third-party script error
- Ad blocker interference

**Fix:**
```
Limited options:
- Can't see full error
- Check third-party status
- Add fallback
- Handle gracefully
```

---

## Quick Error Diagnosis

**When you see an error:**

```
1. Read the full message
2. Note the file and line number
3. Check stack trace
4. Google if unclear
5. Give to AI with context
```

**Error template for AI:**
```
Error: [Paste full error]
Stack trace: [Paste if available]
When: [What triggers it]
Browser: [Which one]

What does this mean and how do I fix it?
```
```