# Debugging

> Diagnose and fix bugs. Use when tracking down errors, analyzing stack traces, reviewing logs, or implementing debugging tools.

- Skill: `hallucinaut/debugging` (Agent Skill)
- Install (CLI): `npx skillmds@latest add hallucinaut/debugging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hallucinaut/debugging/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: hallucinaut (https://skillmd.com/u/hallucinaut)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hallucinaut/debugging

---


# Debugging Skill

Diagnose and fix software issues efficiently.

## When to Use

Use this skill when the user wants to:
- Analyze error messages and stack traces
- Debug failing tests
- Investigate crashes and exceptions
- Review application logs
- Set up debugging tools
- Improve error handling
- Create diagnostic utilities

## Debugging Process

### 1. Reproduce the Issue
- Understand the problem statement
- Identify conditions that trigger the bug
- Create minimal reproduction case

### 2. Gather Information
- Review logs and error messages
- Check stack traces
- Inspect application state
- Review configuration

### 3. Analyze the Code
- Trace execution path
- Identify logical errors
- Check for edge cases
- Verify assumptions

### 4. Hypothesize Causes
- List potential root causes
- Prioritize likely issues
- Form testable hypotheses

### 5. Test Hypotheses
- Add debug logging
- Use breakpoints
- Modify behavior intentionally
- Verify predictions

### 6. Fix and Verify
- Implement fix
- Test fix thoroughly
- Verify no regressions
- Document the fix

## Debugging Techniques

### For Code
- **Breakpoints**: Pause execution at specific points
- **Stepping**: Move through code line by line
- **Watch variables**: Monitor variable values
- **Call stacks**: Understand call hierarchy
- **Linter tools**: Catch syntax errors

### For Logs
- **Structured logging**: Organized log entries
- **Correlation IDs**: Track requests through system
- **Log levels**: Filter by importance
- **Log rotation**: Manage log file size
- **Centralized logging**: Aggregated log storage

### For Production
- **Error tracking**: Production error monitoring
- **Performance profiling**: Identify bottlenecks
- **Resource usage**: Monitor memory, CPU, network
- **Distributed tracing**: Track requests across services

## Common Bug Patterns

### Logic Errors
- Off-by-one errors
- Incorrect conditionals
- Wrong operators
- Edge case failures

### Resource Issues
- Memory leaks
- Infinite loops
- Deadlocks
- Resource exhaustion

### Integration Errors
- API mismatches
- Protocol incompatibilities
- Wrong data types
- Timing issues

### Configuration Errors
- Wrong values
- Missing environment variables
- Misconfigured settings
- Dependency issues

## Best Practices

- **Log everything important**: Errors, warnings, relevant state changes
- **Make logs searchable**: Structured format, meaningful keys
- **Use meaningful error messages**: Explain what and why
- **Add context**: Request ID, user info, timestamps
- **Don't log secrets**: Never log passwords, tokens, API keys
- **Add assertions**: Fail fast when assumptions are violated

## Debugging Tools

### IDE Tools
- Breakpoints
- Debugger
- Linting
- IDE features

### Runtime Tools
- Profilers
- Memory profilers
- Tracing tools
- Network inspection

### Production Tools
- Error tracking
- Monitoring
- Logging aggregation
- APM (Application Performance Monitoring)

## Deliverables

- Bug diagnosis report
- Fix implementation
- Test cases for the bug
- Updated documentation
- Debugging utilities (if needed)

## Quality Checklist

- Bug is reproducible with clear steps
- Root cause is identified
- Fix addresses the root cause
- No regressions introduced
- Tests are added for the fix
- Documentation is updated