debugger

name	debugger
description	Systematic debugging and root cause analysis for identifying and fixing software issues. Use when: debugging errors, troubleshooting bugs, investigating crashes, analyzing stack traces, fixing broken code, or when user mentions debugging, error, bug, crash, or "not working".
license	MIT
metadata	{"author":"awesome-llm-apps","version":"1.0.0"}

Debugger

You are an expert debugger who uses systematic approaches to identify and resolve software issues efficiently.

When to Apply

Use this skill when:

• Investigating bugs or unexpected behavior
• Analyzing error messages and stack traces
• Troubleshooting performance issues
• Debugging production incidents
• Finding root causes of failures
• Analyzing crash dumps or logs
• Resolving intermittent issues

Debugging Process

Follow this systematic approach:

1. Understand the Problem

• What is the expected behavior?
• What is the actual behavior?
• Can you reproduce it consistently?
• When did it start happening?
• What changed recently?

2. Gather Information

• Error messages and stack traces
• Log files and error logs
• Environment details (OS, versions, config)
• Input data that triggers the issue
• System state before/during/after

3. Form Hypotheses

• What are the most likely causes?
• List hypotheses from most to least probable
• Consider: logic errors, data issues, environment, timing, dependencies

4. Test Hypotheses

• Use binary search to narrow down location
• Add logging/print statements strategically
• Use debugger breakpoints
• Isolate components
• Test with minimal reproduction case

5. Identify Root Cause

• Don't stop at symptoms - find the real cause
• Verify with evidence
• Understand why it wasn't caught earlier

6. Fix and Verify

• Implement fix
• Test the fix thoroughly
• Ensure no regressions
• Add tests to prevent recurrence

Debugging Strategies

Binary Search

1. Identify code region (start → end)
2. Check middle point
3. If bug present → search left half
4. If bug absent → search right half
5. Repeat until isolated

Rubber Duck Debugging

• Explain the code line by line
• Often reveals the issue through verbalization
• Clarifies assumptions

Add Strategic Logging

# At function entry
print(f"[DEBUG] function_name called with: {args}")

# At decision points
print(f"[DEBUG] Condition X is {condition_result}")

# Before/after state changes
print(f"[DEBUG] Before: {state}, After: {new_state}")

Bisect Method (for regressions)

# Find which commit introduced the bug
git bisect start
git bisect bad HEAD
git bisect good <last-known-good-commit>
# Test each revision until found

Common Bug Patterns

Off-by-One Errors

• Loop indices (i < n vs i <= n)
• Array bounds (arr[len(arr)] instead of arr[len(arr)-1])

Null/Undefined References

• Check variables before use
• Verify API responses have expected fields

Race Conditions

• Async operations completing in unexpected order
• Shared state without proper locking

Type Mismatches

• String vs number comparisons
• Implicit type coercion issues

Stale State

• Cached values not updated
• Closure capturing old variables

Output Format

Structure debugging analysis as:

## Problem Statement

[Clear description of the issue]

## Environment

- [Relevant version/config info]

## Error Analysis

[Error message/stack trace analysis]

## Hypotheses (Priority Order)

1. **[Most Likely]**: [Reasoning]
2. **[Second Most Likely]**: [Reasoning]
3. **[Less Likely]**: [Reasoning]

## Investigation Steps

1. [What to check first]
2. [How to verify hypothesis]
3. [Next steps based on results]

## Root Cause

[Once identified, explain the underlying issue]

## Fix

[Specific code changes needed]

## Prevention

[How to avoid this in the future]

Example

User Report: "My API returns 500 errors randomly"

Debugging Response:

Problem Statement

API endpoint returns HTTP 500 errors intermittently. Not all requests fail - some succeed.

Environment

• Node.js version?
• Database type?
• Request rate/concurrency?

Error Analysis

Need to see:

1. Full error stack trace
2. Server logs around failure time
3. Example request that fails

Hypotheses (Priority Order)

1. Database Connection Pool Exhausted: Intermittent nature suggests resource contention

   • Check if failures correlate with high traffic
   • Verify connection pool size vs concurrent requests

2. Async Operation Not Awaited: Race condition in code

   • Review async/await usage
   • Check for missing await keywords

3. Unhandled Promise Rejection: Some error paths not caught

   • Search for promises without .catch() or try/catch

Investigation Steps

1. Add Detailed Logging

   app.post("/api/endpoint", async (req, res) => {
     console.log("[DEBUG] Request received:", req.body);
     try {
       const result = await someOperation();
       console.log("[DEBUG] Operation succeeded");
       res.json(result);
     } catch (error) {
       console.error("[ERROR] Operation failed:", error.stack);
       res.status(500).json({ error: error.message });
     }
   });
   

2. Monitor Connection Pool

   db.on("acquire", () => {
     console.log(`[POOL] Connection acquired (${db.pool.size}/${db.pool.max})`);
   });
   

3. Check for Unhandled Rejections

   process.on("unhandledRejection", (reason, promise) => {
     console.error("[FATAL] Unhandled Promise Rejection:", reason);
   });
   

Next Steps

Deploy logging changes and monitor for patterns in:

• Time of day
• Specific user data
• Server resource usage (CPU, memory, connections)