debug-helper by einverne

---
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
```python
# 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)**
```python
import pdb; pdb.set_trace()  # Breakpoint
# Or with Python 3.7+
breakpoint()
```

**Node.js**
```javascript
debugger;  // Breakpoint in Chrome DevTools
```

**GDB (C/C++)**
```bash
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
```bash
# 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
```bash
# Linux
strace -e open,read,write command
strace -p PID

# macOS
dtruss -f command
```

### Check Logs
```bash
# 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
```bash
# 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
```bash
# Profile script
time command
hyperfine 'command1' 'command2'

# Find slow SQL queries
EXPLAIN ANALYZE SELECT ...

# Profile Python
python -m cProfile script.py
```

### Memory Issues
```bash
# 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?