Debug Skill
Unified debugging, testing, and error-fixing for full-stack applications.
When to Use
| Trigger |
Action |
| Bug report, error, crash |
Start 4-phase debugging |
| Need tests |
Run biome + vitest |
| Frontend broken |
Use agent-browser CLI |
| Slow queries |
Use Neon MCP tools |
| Deployment failed |
Check Railway logs |
Content Map
| Reference |
Purpose |
| Testing Pyramid |
Unit/Integration/E2E selection |
| Debug Methodology |
4-phase process, 5 Whys |
| Security Checklist |
OWASP Top 10 2025 |
Decision Tree: Which Tool?
Problem Type?
├── Backend Error
│ ├── Type error → bun run check
│ ├── Logic error → bun test
│ └── API error → Check tRPC logs
├── Database Error
│ ├── Slow query → mcp_mcp-server-neon_list_slow_queries
│ ├── Schema issue → drizzle-kit push
│ └── Connection → Check DATABASE_URL
├── Frontend Error
│ ├── Visual bug → agent-browser snapshot/screenshot
│ ├── Interaction → agent-browser click/fill
│ └── Console error → browser_subagent
└── Deployment Error
└── Railway → railway logs --filter="level:error"
CLI Quick Reference
Backend: Biome + Vitest
# Lint & type check
bun run check
# Run tests
bun test
bun test --coverage
bun test path/to/file.test.ts
Frontend: agent-browser CLI
# Install (first time)
npm install -g agent-browser
agent-browser install
# Core workflow
agent-browser open http://localhost:3000 # Navigate
agent-browser snapshot # Get refs (a11y tree)
agent-browser click @e2 # Click element by ref
agent-browser fill @e3 "test@example.com" # Fill input
agent-browser get text @e1 # Get text content
agent-browser screenshot page.png # Capture state
agent-browser close # Cleanup
Database: Neon MCP
# Via MCP (preferred)
mcp_mcp-server-neon_list_slow_queries # Find slow queries
mcp_mcp-server-neon_run_sql # Execute debug SQL
mcp_mcp-server-neon_explain_sql_statement # Analyze query plan
# Via CLI
neonctl databases list --project-id <id>
Deployment: Railway CLI
# View logs
railway logs
# Filter errors
railway logs --filter="level:error"
# Filter path + error
railway logs --filter="@path:/api level:error"
# SSH into service (interactive)
railway ssh --service <service-id>
4-Phase Debugging Process
Phase 1: REPRODUCE
Phase 2: ISOLATE
Phase 3: UNDERSTAND (Root Cause)
Phase 4: FIX & VERIFY
5 Whys Template
**Problem**: [Describe error]
1. Why? → [First cause]
2. Why? → [Deeper cause]
3. Why? → [Underlying issue]
4. Why? → [Systemic reason]
5. Why? → [Root cause]
**Root Cause**: [Final determination]
**Fix**: [Solution implemented]
Testing Pyramid
/\
/E2E\ ← Few, slow, high confidence
/------\
/ Integ. \ ← Some, medium speed
/----------\
/ Unit \ ← Many, fast, isolated
/--------------\
| Layer |
Tool |
When |
| Unit |
Vitest |
Business logic, utils |
| Integration |
Vitest + tRPC |
API routes, DB queries |
| E2E |
agent-browser |
User flows, UI |
Security Quick Check (OWASP 2025)
| # |
Vulnerability |
Check |
| 1 |
Broken Access Control |
Verify auth on all routes |
| 2 |
Cryptographic Failures |
Check secrets not exposed |
| 3 |
Injection |
Parameterized queries only |
| 4 |
Insecure Design |
Review auth flow |
| 5 |
Security Misconfig |
Check CORS, headers |
Scripts
| Script |
Purpose |
run_tests.sh |
Run biome + vitest |
fetch_logs.sh |
Aggregate error logs |
frontend_test.sh |
agent-browser testing |
Anti-Patterns
❌ Don't skip reproduction steps
❌ Don't fix symptoms without root cause
❌ Don't ignore type errors
❌ Don't deploy without tests passing
❌ Don't use console.log in production
Output Template
When debugging is complete, document:
## Debug Report
**Issue**: [Description]
**Root Cause**: [5 Whys result]
**Fix**: [What was changed]
**Verification**:
- [ ] `bun run check` ✅
- [ ] `bun test` ✅
- [ ] Browser verified ✅
**Files Changed**: [list]
majiayu000