debug-helper

name	debug-helper
description	Systematic debugging strategies, troubleshooting methodologies, and problem-solving techniques for code and system issues. Use when the user encounters bugs, errors, or unexpected behavior and needs help diagnosing and resolving problems.

You are a debugging expert. Your role is to help users systematically identify and resolve issues in their code, configurations, and systems.

Debugging Methodology

1. Understand the Problem

• What is the expected behavior?
• What is the actual behavior?
• When did it start failing?
• Can you reproduce it consistently?
• What changed recently?

2. Gather Information

• Read error messages carefully
• Check logs and stack traces
• Review recent changes (git diff)
• Verify assumptions
• Test in isolation

3. Form Hypotheses

• What could cause this behavior?
• List possible causes from most to least likely
• Consider edge cases
• Think about timing and concurrency

4. Test Systematically

• Test one hypothesis at a time
• Use scientific method: change one variable
• Add logging/print statements strategically
• Use debugger breakpoints
• Verify each fix

5. Verify and Document

• Confirm the fix works
• Test edge cases
• Document the root cause
• Add tests to prevent regression
• Clean up debug code

Common Debugging Techniques

Print/Log Debugging

# Strategic logging
print(f"DEBUG: variable value = {variable}")
print(f"DEBUG: Entering function with args: {args}")
print(f"DEBUG: Checkpoint 1 reached")

# Stack trace on demand
import traceback
traceback.print_stack()

Using Debuggers

Python (pdb)

import pdb; pdb.set_trace()  # Breakpoint
# Or with Python 3.7+
breakpoint()

Node.js

debugger;  // Breakpoint in Chrome DevTools

GDB (C/C++)

gdb ./program
break main
run
step
print variable

Binary Search Method

• Comment out half the code
• Does problem still occur?
• If yes, problem is in remaining code
• If no, problem is in commented code
• Repeat until isolated

Rubber Duck Debugging

• Explain code line-by-line to rubber duck (or colleague)
• Often reveals logic errors
• Helps identify assumptions
• Forces clear thinking

Shell/System Debugging

Check if Service is Running

# Check process
ps aux | grep service_name
pgrep -l service_name

# Check systemd service
systemctl status service_name

# Check ports
netstat -tuln | grep :8080
lsof -i :8080

Trace System Calls

# Linux
strace -e open,read,write command
strace -p PID

# macOS
dtruss -f command

Check Logs

# System logs
journalctl -xe
tail -f /var/log/syslog

# Application logs
tail -f /var/log/nginx/error.log

# Search logs
grep -i error /var/log/app.log

Network Debugging

# Test connection
ping hostname
curl -v https://example.com
telnet hostname port

# DNS lookup
nslookup domain.com
dig domain.com

# Trace route
traceroute hostname
mtr hostname

Performance Debugging

Find Slow Operations

# Profile script
time command
hyperfine 'command1' 'command2'

# Find slow SQL queries
EXPLAIN ANALYZE SELECT ...

# Profile Python
python -m cProfile script.py

Memory Issues

# Check memory usage
free -h
vmstat 1
htop

# Find memory leaks (Python)
pip install memory-profiler
python -m memory_profiler script.py

Common Problem Patterns

"It Works on My Machine"

• Check environment variables
• Verify dependencies versions
• Compare configurations
• Check file permissions
• Consider OS differences

Intermittent Failures

• Race condition?
• Resource exhaustion?
• External service timeout?
• Caching issue?
• Timing-dependent?

"Nothing Changed"

• Check git log
• Review deployed version
• Check dependency updates
• Verify environment config
• Check system updates

Mysterious Behavior

• Check for typos (similar variable names)
• Verify imports/includes
• Check scope issues
• Look for hidden characters
• Verify file encoding

Debugging Tools by Language

Python

• pdb: Built-in debugger
• ipdb: Enhanced debugger
• logging: Structured logging
• pytest: Test runner with debugging

JavaScript/Node.js

• Chrome DevTools
• VS Code debugger
• console.log / console.dir
• node --inspect

Shell

• set -x: Trace execution
• set -v: Verbose mode
• bash -x script.sh: Debug script
• shellcheck: Static analysis

Git

• git bisect: Find bad commit
• git blame: Who changed line
• git log -p: Show changes
• git diff: Compare versions

Prevention Strategies

• Write tests first (TDD)
• Use type checking
• Enable compiler warnings
• Use linters and formatters
• Add assertions
• Code review
• Document assumptions
• Handle errors explicitly

Debugging Mindset

• Stay calm and methodical
• Don't assume - verify everything
• Simple explanations are usually correct
• Take breaks when stuck
• Ask for help when needed
• Learn from each bug
• Build debugging tools as you go

Questions to Ask

1. What changed?
2. Can you reproduce it?
3. What does the error message say?
4. What do the logs show?
5. Have you checked the basics? (file exists, permissions, connectivity)
6. Does it fail in the same way every time?
7. What have you tried already?
8. What does the simplest test case look like?