# Debug > Provides a structured debugging workflow for non-technical founders, covering reproduction, diagnostic gathering, and AI-assisted fixes. - Skill: `diegosouzapw/debug` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add diegosouzapw/debug` - Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/debug/raw - Safety review: PASS (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity, AI & ML, Docs & Writing - Tags: Ai Assisted Debugging, Browser Devtools, Bug Reproduction, Debugging, Error Messages - Author: diegosouzapw (https://skillmd.com/u/diegosouzapw) - Updated: 2026-08-22 - Page: https://skillmd.com/skills/diegosouzapw/debug --- # 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)