YAML
---
name: debugging-systems
description: Systematically identifies and resolves technical issues through structured troubleshooting methodology. Use when encountering bugs, system failures, or unexpected behavior.
---

# Quick Start

```bash
# Basic debug workflow
1. Reproduce the issue consistently
2. Check logs: tail -f /var/log/application.log
3. Isolate variables: disable features one by one
4. Test hypothesis: implement minimal fix
5. Verify solution: run full test suite

Workflow

Progress:

• Reproduce - Can you make it happen again?
• Isolate - What's the minimal case that triggers it?
• Gather data - Logs, error messages, system state
• Form hypothesis - What do you think is causing it?
• Test - Make one change at a time
• Verify - Confirm the fix works and doesn't break anything else

Data Collection

1. Error messages - Full stack traces, not just summaries
2. System logs - Application, system, database logs
3. Environment - OS, versions, configurations
4. Timing - When did it start? What changed recently?
5. Scope - Affects all users or specific subset?

Examples

Example 1: Input: "Application randomly crashes" Output:

1. Check crash logs: /var/crash/app_*.crash
2. Monitor memory usage: top -p <pid>
3. Test with minimal data set
4. Review recent code changes
5. Run under debugger: gdb ./app core

Example 2: Input: "Database query is slow" Output:

SQL
-- Enable query logging
SET log_statement = 'all';
-- Check execution plan
EXPLAIN ANALYZE SELECT ...;
-- Look for missing indexes
-- Monitor during peak hours

Best Practices

• Change one thing at a time - Multiple changes hide which one fixed it
• Document everything - Keep notes of what you tried
• Use version control - Commit working state before experimenting
• Start with logs - They often contain the answer
• Rubber duck debugging - Explain the problem out loud
• Take breaks - Fresh eyes spot obvious issues

Common Pitfalls

• Assuming the cause - Test your hypothesis, don't just assume
• Fixing symptoms - Address root cause, not just surface issues
• Skipping reproduction - If you can't reproduce it, you can't verify the fix
• Over-engineering fixes - Simple solutions are usually better
• Not testing edge cases - Your fix might break something else