debug
Use this skill when features break, users report errors, deployments fail, or tests don't pass. Guides systematic debugging: reproducing bugs, gathering diagnostic info, reading error messages, and working with AI tools to fix issues efficiently.
whawkinsiv · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add whawkinsiv/solo-founder-skills --skill debugAbout this skill
name: debug description: "Use this skill when features break, users report errors, deployments fail, or tests don't pass. Guides systematic debugging: reproducing bugs, gathering diagnostic info, reading error messages, and working with AI tools to fix issues efficiently."
Debug
The golden rule
NO GUESSING. GATHER INFO FIRST.
Bad: Something broke → try random fix → doesn't work → try another → still broken after 5 attempts.
Good: Something broke → reproduce it → gather diagnostic info → diagnose root cause → fix it (usually first try).
Diagnosis before fixes.
Debugging by tool
How you debug depends on which tool you're using.
Claude Code (you have direct access)
Claude Code can gather its own diagnostics. Before asking the founder for screenshots or logs, do this automatically:
Auto-debug steps (do these yourself):
1. Check git history: git log --oneline -10 and git diff HEAD~3
2. Search for the error: Grep for error text across the codebase
3. Read the failing file: Read the file + surrounding context
4. Run the app/tests: Bash to run dev server, test suite, or reproduce
5. Check logs: Read server logs, build output, or error logs
6. Check environment: Verify .env.example vs actual config
Only ask the founder for information you can't get yourself: what they saw in the browser, what they clicked, screenshots of visual bugs.
Lovable / Replit (founder pastes into chat)
The founder needs to gather info manually and paste it. Use the "Tell AI:" prompts in DEBUG-PROMPTS.md — they're structured templates that ensure complete context.
Production bugs (check monitoring first)
Before debugging production issues, check monitoring and error tracking:
1. Error tracker (Sentry, LogRocket): exact error + stack trace + user context
2. Server logs: filter by timestamp of report
3. Hosting dashboard: any deployment or outage at that time?
4. Database: any failed migrations or connection issues?
See /monitor skill for setting up monitoring. See /deploy skill for rollback procedures.
Workflow
Debug process:
- [ ] Reproduce bug consistently
- [ ] Gather diagnostic info (auto in Claude Code, manual elsewhere)
- [ ] Check what changed recently
- [ ] Diagnose root cause before proposing fixes
- [ ] Fix the root cause
- [ ] Test fix works
- [ ] Verify didn't break anything else
- [ ] Ask: how do we prevent this?
Reproducing bugs
Before fixing, reproduce it:
Can you reproduce it?
- [ ] Exact steps to trigger bug
- [ ] Happens every time or intermittently?
- [ ] Specific browser/device?
- [ ] Specific data or user?
If can't reproduce:
- Ask user for exact steps or screen recording
- Try different browser/device/account
- Try with different data
- Clear cache and retry
- Check if timing-dependent
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
- Right-click page → Inspect → Console tab
- Look for red errors
- Screenshot the full error including stack trace
Tell AI:
Console error: [paste full error message]
When it happens: [what you were doing]
Network tab
- DevTools → Network tab → reproduce bug
- Look for failed requests (red, 4xx, 5xx)
- Click failed request → check Response tab
Tell AI:
API call failing:
URL: /api/endpoint
Method: [GET/POST]
Status: [status code]
Response: [paste error response]
This happens when: [action]
Visual bugs
Screenshot what you expected vs what actually shows. Include device and browser.
Common bug types
"Nothing happens when I click"
Check: console errors? Network request failing? Element actually clickable (not covered by another element)?
"Page won't load"
Check: network errors? JavaScript errors? Infinite redirect? Missing environment variable?
"Wrong data showing"
Check: API returning wrong data (network tab)? Caching issue? State not updating? Wrong user context?
"Form doesn't submit"
Check: validation errors visible? Console errors? Network request firing at all?
"Works in dev, broken in production"
Check: environment variables set? Different database? Build step stripping something? CORS configured for production domain?
"Works in Chrome, broken in Safari"
Check: CSS/JS compatibility? Safari-specific defaults? Date parsing differences?
Escalation discipline
After 1 failed fix
Reassess. Did we misdiagnose? Is there more info we should gather?
Fix didn't work. Here's what happened after applying it: [new info].
Are we fixing the right thing?
After 2 failed fixes
Stop trying fixes. The diagnosis is probably wrong.
2 fixes failed.
Fix 1: [tried] → [result]
Fix 2: [tried] → [result]
Are we fixing the wrong thing? Should we rethink the approach entirely?
After 3 failed fixes
Don't try a 4th. Change strategy:
- Rebuild the feature with a simpler approach
- Get a human developer to look at it (see /hiring)
- Ship a workaround and fix properly later
Digging deeper: find the real root cause
Most debugging failures happen because you stop at the first plausible cause instead of the actual root cause. Use the "keep asking why" technique:
Problem: Server crashed
Why? → Out of memory
Why? → Memory leak in the auth service ← Most people stop here and "add more RAM"
Why? → Database connections not being released
Why? → Error handler doesn't close connections
Why? → No cleanup in the finally block ← THIS is the fix
How to tell you've found the real root cause:
- It's something you can actually change (code, config, process)
- Fixing it would prevent the problem from recurring
- Asking "why?" again doesn't lead anywhere actionable
Common mistake: stopping at "the AI broke it." That's
Read the complete source ↗