Menu
Systematic debugging methodology, log analysis, and error diagnosis for software development workflows.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
PersonalOS skill: account-management
API endpoint testing, mocking, and integration testing for robust API development.
Optimize images, icons, and design assets for performance, quality, and developer handoff
Plan, track, and optimize budgets to maximize value and financial performance
CI/CD pipeline optimization, build failures, and deployment automation for DevOps workflows.
Code quality improvement, technical debt reduction, and refactoring patterns for maintainable software.
| name | debugging |
| description | Systematic debugging methodology, log analysis, and error diagnosis for software development workflows. |
Systematic debugging methodology for identifying, diagnosing, and resolving software issues efficiently.
Helps you debug software issues systematically using proven debugging methodologies and error analysis techniques.
Questions to Answer:
Template:
Problem Definition:
- Symptom: [what went wrong]
- Occurs when: [timing/conditions]
- Expected: [what should happen]
- Actual: [what actually happens]
- Impact: [how severe is this?]
Sources to Check:
Information Collection Checklist:
✓ Error message text
✓ Stack trace (if available)
✓ Relevant log entries
✓ Reproduction steps
✓ Environment details (OS, versions, config)
✓ Recent changes
Reproduction Strategy:
Minimal Reproduction:
Minimal Example:
- Simplify inputs
- Reduce dependencies
- Remove unrelated code
- Isolate the failing component
Hypothesis Generation:
Hypothesis Template:
Hypothesis: [I believe X is causing Y]
Because: [evidence/reasoning]
Test: [how to verify]
Expected: [if hypothesis is true, what happens?]
Testing Approach:
Test Documentation:
Test: [what you tested]
Result: [pass/fail with evidence]
Conclusion: [what this tells us]
Next: [next step based on result]
Isolation Techniques:
Isolation Questions:
Fix Strategy:
Fix Checklist:
✓ Addresses root cause (not just symptoms)
✓ Minimal code changes
✓ Tested with reproduction case
✓ Tested edge cases
✓ Doesn't break existing functionality
✓ Documented with comments
Verification Steps:
Works With:
5 Whys Technique:
Problem: [issue]
Why 1: [first reason]
Why 2: [second reason]
Why 3: [third reason]
Why 4: [fourth reason]
Why 5: [root cause]
Fishbone Diagram:
Example Categories:
Log Query Patterns:
# Find all errors in last hour
grep -i "error" application.log | tail -100
# Find errors by user
grep "user_123" application.log | grep -i "error"
# Correlate errors across services
grep -i "error" app1.log | awk '{print $3}' | xargs -I{} grep {} app2.log
# Time-based analysis
awk '/2026-03-27 14:00/,/2026-03-27 15:00/' application.log
Log Aggregation Strategies:
Profiling Approach:
1. Identify performance bottleneck
2. Measure current performance (baseline)
3. Profile the code (CPU, memory, I/O)
4. Identify hot spots
5. Optimize targeted areas
6. Measure improvement
7. Repeat if needed
Common Performance Issues:
Profiling Tools:
Common Concurrency Issues:
Debugging Strategies:
1. Identify shared resources
2. Analyze access patterns
3. Check for proper synchronization
4. Look for non-atomic operations
5. Verify lock ordering (deadlock prevention)
6. Test with different thread counts
7. Use thread sanitizers (when available)
Thread Sanitizer Examples:
# GCC/Clang
gcc -fsanitize=thread -g program.c -o program
./program
# Go
go test -race ./...
Memory Leak Detection:
1. Take memory snapshot (baseline)
2. Perform operations that might leak
3. Take another memory snapshot
4. Compare snapshots - look for growing objects
5. Trace references to find why objects aren't collected
Common Memory Issues:
Memory Profiling Tools:
Challenges:
Distributed Tracing:
1. Add trace IDs to requests
2. Propagate trace IDs across services
3. Log trace IDs in all services
4. Use tracing tools (Jaeger, Zipkin, Datadog APM)
5. Analyze request flows and latency
Debugging Checklist:
✓ Trace the request through all services
✓ Check for timeouts and retries
✓ Verify data consistency
✓ Check network connectivity
✓ Review recent deployments
✓ Check configuration changes
✓ Look for resource exhaustion
Log Levels:
Structured Logging:
{
"timestamp": "2026-03-27T14:30:00Z",
"level": "ERROR",
"service": "payment-service",
"request_id": "abc-123",
"user_id": "user-456",
"message": "Payment failed",
"error_code": "PAYMENT_DECLINED",
"amount": 99.99,
"currency": "USD"
}
Testing Debugging Hypotheses:
# Create a minimal test case
def test_bug_reproduction():
# Arrange
data = {"value": 42}
# Act
result = buggy_function(data)
# Assert
assert result == expected_value # This will fail
Common Debugger Features:
Bug Report Template:
Title: [Concise description]
Description:
[Detailed explanation of the issue]
Steps to Reproduce:
1. [Step 1]
2. [Step 2]
3. [Step 3]
Expected Behavior:
[What should happen]
Actual Behavior:
[What actually happens]
Environment:
- OS: [operating system]
- Version: [software version]
- Configuration: [relevant settings]
Attachments:
- Screenshots
- Logs
- Code snippets
Multi-Skill Workflows:
1. Use quick-research to understand error messages
2. Use knowledge-graph to find similar past issues
3. Use code-review to find related code patterns
4. Use debugging skill to isolate and fix issue
5. Use code-refactoring to prevent recurrence
6. Use workflow-orchestrator to automate debugging tasks
Pattern Recognition:
Implementation:
1. Track bug history (types, causes, locations)
2. Identify high-risk code areas
3. Code smells analysis (complexity, coupling, coverage)
4. Suggest refactoring or testing
Risk Indicators:
Self-Diagnosing Systems:
1. System monitors its own health
2. Detects anomalies (metrics, logs, errors)
3. Automatically collects debugging information
4. Attempts self-recovery (restart, rollback)
5. Escalates to human if needed
Health Checks:
def health_check():
checks = {
"database": check_database(),
"cache": check_cache(),
"api": check_external_api(),
"disk_space": check_disk_space(),
}
return all(checks.values()), checks
Debugging Tools Integration:
Automated Alerting:
1. Define alert conditions (error rate, latency, anomalies)
2. Set up monitoring dashboards
3. Configure alert notifications (email, Slack, PagerDuty)
4. Create runbooks for common issues
5. Automate initial diagnosis steps
Building a Debugging Knowledge Graph:
1. Document all bugs and their fixes
2. Link bugs to symptoms, causes, and solutions
3. Tag by component, severity, frequency
4. Enable semantic search for bug patterns
5. Learn from debugging history
Knowledge Base Schema:
{
"bug_id": "BUG-123",
"symptoms": ["error message", "stack trace"],
"root_cause": "null pointer dereference",
"fix": "add null check",
"prevention": "add defensive coding",
"related_bugs": ["BUG-100", "BUG-200"],
"component": "payment-service",
"frequency": 5,
"severity": "high"
}
When Needed:
Tools:
Challenges:
Tools:
kdump and crash (Linux)dtrace and perf (Linux)eBPF (Linux)systemtap (Linux)Common Issues:
Tools:
tcpdump and wireshark (packet capture)netstat and ss (network connections)traceroute and ping (routing)dig and nslookup (DNS)openssl s_client (SSL/TLS)Common Issues:
Tools:
EXPLAIN, EXPLAIN ANALYZE)pg_stat_statements, Performance Schema)Post-Mortem Format:
1. Executive Summary
- What happened
- Impact
- Timeline
2. Root Cause Analysis
- How did it happen
- Contributing factors
- Systemic issues
3. Resolution
- What we did to fix it
- Timeline of fixes
4. Lessons Learned
- What went well
- What didn't
- What to improve
5. Action Items
- Prevent recurrence
- Improve detection
- Better documentation
Blameless Principles:
Continuous Improvement:
Metrics:
Do:
Don't:
Problem:
Database connection timeout after 30 seconds
Tier 1 Approach:
Tier 2 Approach:
Tier 3 Approach:
Problem:
Application runs out of memory after 24 hours
Tier 1 Approach:
Tier 2 Approach:
Tier 3 Approach:
Problem:
Intermittent data corruption under load
Tier 1 Approach:
Tier 2 Approach:
Tier 3 Approach:
Problem: Jumping into code without understanding the issue Fix: Start with problem definition and gather information first
Problem: Adding error handling instead of fixing underlying bug Fix: Use root cause analysis (5 Whys, fishbone diagram)
Problem: Making fixes without confirming they work Fix: Always create a reproducible test case
Problem: Changing multiple things, don't know which fixed it Fix: Make minimal changes, test each change
Problem: Fix works for main case but fails edge cases Fix: Test with various inputs and conditions
Problem: Forgetting what was learned, repeating same mistakes Fix: Document bugs, fixes, and lessons learned
Problem: Print statements are inefficient and hard to manage Fix: Use proper logging and debugging tools
Problem: Issue recurs later, no way to detect Fix: Add monitoring and alerting for recurrence
A: Collect as much information as possible from the original occurrence (logs, screenshots, environment details). Try to understand the conditions that led to the issue. Create tests based on your understanding, even if they don't fail.
A: Intermittent bugs are often timing-related (race conditions) or data-dependent. Focus on concurrency, timing, and data variations. Use stress testing to increase frequency of occurrence. Add detailed logging to capture state when the bug occurs.
A: Start with understanding the inputs and outputs. Trace the execution path. Simplify by removing unrelated code. Use a debugger to step through code. Ask for help from someone familiar with the code.
A: The root cause is the deepest level cause that, if addressed, prevents the issue from recurring. Use the "5 Whys" technique or fishbone diagram to ensure you've reached the root cause, not just a symptom.
A: Always fix the actual bug first. Defensive coding is appropriate as a safety net, but not as a substitute for fixing the root cause.