Skip to main content

Debugging Checklist Prompt

Context​

Use this systematic approach when debugging issues in Pacing Agency projects. Covers common debugging scenarios, tools, and techniques for web apps, APIs, infrastructure, and integrations.

Prompt Template​

I need to debug the following issue:

**Problem Description:**
- Issue: [ISSUE_DESCRIPTION]
- When it occurs: [OCCURRENCE_PATTERN]
- Expected behavior: [EXPECTED_BEHAVIOR]
- Actual behavior: [ACTUAL_BEHAVIOR]
- Error messages: [ERROR_MESSAGES]

**Environment:**
- Project: [PROJECT_NAME]
- Environment: [ENVIRONMENT] (Local/Staging/Production)
- Browser/Platform: [PLATFORM]
- Recent changes: [RECENT_CHANGES]

**Already Tried:**
- Attempted solutions: [SOLUTIONS_TRIED]
- Results: [RESULTS]

Please provide:

1. **Systematic debugging approach** for this specific issue
2. **Tools and commands** to gather more information
3. **Common causes** for this type of issue
4. **Step-by-step troubleshooting** process
5. **How to verify the fix** once resolved
6. **Prevention strategies** to avoid similar issues

Format with clear sections, commands, and expected outputs.

Debugging Process​

1. Reproduce the Issue​

# Document exact steps to reproduce
# Note environment, timing, inputs
# Try to create minimal reproduction case

2. Gather Information​

# Check logs
docker logs [container]
tail -f /var/log/nginx/error.log
journalctl -u servicename -f

# Check system resources
top
df -h
free -h

# Check network
curl -I https://domain.com
dig domain.com
ping server.com

# Check process status
systemctl status nginx
docker ps
pm2 status

3. Isolate the Problem​

  • Is it frontend or backend?
  • Is it environment-specific?
  • Is it related to recent changes?
  • Can you reproduce consistently?

4. Test Hypothesis​

  • Form hypothesis about cause
  • Test with minimal changes
  • Document results
  • Iterate until resolved

5. Implement Fix​

  • Make targeted changes
  • Test thoroughly
  • Document the fix
  • Update related documentation

6. Prevent Recurrence​

  • Add tests for this scenario
  • Improve error messages
  • Add monitoring/alerts
  • Document lessons learned

Common Issue Categories​

Frontend Issues​

React component not rendering

  • Check console for errors
  • Verify import paths
  • Check props are correct
  • Verify component is exported

Styling not applying

  • Check CSS Module import
  • Verify class names match
  • Check theme variables
  • Test in light/dark mode

API call failing

  • Check network tab
  • Verify CORS headers
  • Check authentication
  • Verify API endpoint

Backend/API Issues​

500 Internal Server Error

  • Check server logs
  • Verify environment variables
  • Check database connection
  • Review recent code changes

Authentication failing

  • Verify API keys are correct
  • Check token expiry
  • Verify headers are sent
  • Check CORS configuration

Rate limit exceeded

  • Check API usage
  • Implement rate limiting
  • Add retry logic
  • Consider caching

Infrastructure Issues​

Server not accessible

  • Check server is running
  • Verify firewall rules
  • Check DNS resolution
  • Verify SSL certificate

Service keeps restarting

  • Check container logs
  • Verify resource limits
  • Check port conflicts
  • Review health checks

SSL certificate errors

  • Check certificate expiry
  • Verify DNS is correct
  • Check certificate chain
  • Test with openssl

Integration Issues​

Webhook not triggering

  • Verify webhook URL
  • Check webhook authentication
  • Test webhook manually (curl)
  • Check service logs

Data not syncing

  • Check API credentials
  • Verify data format
  • Check rate limits
  • Review error logs

n8n workflow failing

  • Check node execution logs
  • Test individual nodes
  • Verify credentials
  • Check error handling

Debugging Tools​

Browser DevTools​

  • Console: JavaScript errors
  • Network: API calls, timing
  • Elements: DOM inspection
  • Sources: Breakpoints
  • Performance: Profiling
  • Lighthouse: Audits

Command Line​

# HTTP debugging
curl -v https://api.example.com
curl -I https://example.com

# DNS debugging
dig example.com
nslookup example.com

# Network debugging
ping example.com
traceroute example.com
netstat -tlnp

# SSL debugging
openssl s_client -connect example.com:443
certbot certificates

# Docker debugging
docker logs -f [container]
docker exec -it [container] sh
docker inspect [container]

# System debugging
systemctl status [service]
journalctl -u [service] -f
tail -f /var/log/[logfile]

Node.js/JavaScript​

// Console debugging
console.log('value:', value);
console.error('error:', error);
console.table(arrayOfObjects);

// Debugger statement
debugger; // Pauses execution in browser DevTools

// Performance timing
console.time('operation');
// ... code ...
console.timeEnd('operation');

// Stack trace
console.trace();

Success Criteria​

✅ Issue reproduced consistently
✅ Root cause identified
✅ Fix implemented and tested
✅ Documentation updated
✅ Tests added (if applicable)
✅ Team informed of resolution

Last updated: 2026-01-07
Estimated time: Variable (15 minutes to several hours)