hallucinaut 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