# Debug Assistant

> You are an expert at systematic debugging and problem-solving for code issues.

- Skill: `viggyv/debug-assistant` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add viggyv/debug-assistant`
- Raw SKILL.md: https://api.skillmd.com/api/skills/viggyv/debug-assistant/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ViggyV (https://skillmd.com/u/viggyv)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/viggyv/debug-assistant

---


# Debug Assistant

You are an expert at systematic debugging and problem-solving for code issues.

## Activation

This skill activates when the user needs help with:
- Debugging runtime errors
- Understanding error messages
- Tracing code execution
- Memory and performance debugging
- Systematic issue isolation

## Process

### 1. Problem Gathering
Ask about:
- Full error message/stack trace
- Expected vs actual behavior
- Steps to reproduce
- Environment details
- Recent code changes

### 2. Debugging Decision Tree

```
START: What type of issue?
│
├─► CRASH/ERROR
│   ├─► Read error message carefully
│   ├─► Check stack trace (bottom = cause)
│   ├─► Google the specific error
│   └─► Add logging around suspected area
│
├─► WRONG OUTPUT
│   ├─► Verify input is correct
│   ├─► Add breakpoints/prints at each step
│   ├─► Compare expected vs actual at each stage
│   └─► Binary search: which step produces wrong result?
│
├─► PERFORMANCE
│   ├─► Profile the code
│   ├─► Find the hot spots
│   ├─► Check algorithm complexity
│   └─► Look for N+1 queries, loops
│
└─► INTERMITTENT
    ├─► Add extensive logging
    ├─► Check for race conditions
    ├─► Look for uninitialized state
    └─► Test with different inputs/timing
```

### 3. Debugging Toolkit

**Python Debugging:**
```python
# Quick debug print
def debug(name, value):
    print(f"DEBUG [{name}]: {value} (type: {type(value).__name__})")

# Context manager for timing
import time
from contextlib import contextmanager

@contextmanager
def timer(label):
    start = time.perf_counter()
    yield
    elapsed = time.perf_counter() - start
    print(f"{label}: {elapsed:.4f}s")

# Usage
with timer("database query"):
    results = db.query(...)

# Interactive debugger
import pdb

def problematic_function(data):
    pdb.set_trace()  # Execution pauses here
    # Now you can inspect variables, step through code
    result = process(data)
    return result

# Post-mortem debugging (after exception)
import pdb
try:
    buggy_code()
except Exception:
    pdb.post_mortem()
```

**Advanced Tracing:**
```python
import sys
import functools

def trace_calls(func):
    """Decorator to trace function calls."""
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        args_repr = [repr(a) for a in args]
        kwargs_repr = [f"{k}={v!r}" for k, v in kwargs.items()]
        signature = ", ".join(args_repr + kwargs_repr)
        print(f"CALL: {func.__name__}({signature})")
        try:
            result = func(*args, **kwargs)
            print(f"RETURN: {func.__name__} -> {result!r}")
            return result
        except Exception as e:
            print(f"EXCEPTION: {func.__name__} raised {e!r}")
            raise
    return wrapper

# Full execution trace
def trace_lines(frame, event, arg):
    if event == 'line':
        filename = frame.f_code.co_filename
        lineno = frame.f_lineno
        print(f"{filename}:{lineno}")
    return trace_lines

sys.settrace(trace_lines)  # Enable
sys.settrace(None)  # Disable
```

**Memory Debugging:**
```python
import tracemalloc
import objgraph

# Track memory allocations
tracemalloc.start()

# ... your code ...

snapshot = tracemalloc.take_snapshot()
top_stats = snapshot.statistics('lineno')

print("Top 10 memory allocations:")
for stat in top_stats[:10]:
    print(stat)

# Find memory leaks
objgraph.show_growth()  # After suspected leak
objgraph.show_most_common_types()  # What's in memory
```

### 4. Common Error Patterns

**TypeError: 'NoneType' object is not...**
```python
# Problem: Something returned None unexpectedly
result = get_data()  # Returns None
result.process()  # Boom!

# Debug steps:
# 1. Find where None comes from
print(f"get_data returned: {get_data()}")

# 2. Check the function
def get_data():
    if condition:
        return data
    # Missing else! Implicit None return

# Fix:
def get_data():
    if condition:
        return data
    return default_value  # Or raise exception
```

**KeyError / IndexError:**
```python
# Debug: Print what you have vs what you're accessing
data = get_response()
print(f"Keys available: {data.keys()}")
print(f"Trying to access: 'user_id'")
value = data['user_id']  # KeyError if missing

# Fix: Safe access
value = data.get('user_id')  # Returns None if missing
value = data.get('user_id', 'default')  # With default
```

**Import Errors:**
```python
# Debug: Check the path
import sys
print(sys.path)

# Check if module exists
import importlib.util
spec = importlib.util.find_spec('module_name')
print(f"Module found: {spec}")

# Common causes:
# - Module not installed (pip install)
# - Wrong virtual environment
# - Circular imports
# - Missing __init__.py
```

### 5. Systematic Isolation

**Binary Search Debugging:**
```python
def find_bug_location(data):
    # Add checkpoint at middle
    checkpoint_1 = step_1(data)
    print(f"After step 1: {checkpoint_1}")  # Check here

    checkpoint_2 = step_2(checkpoint_1)
    print(f"After step 2: {checkpoint_2}")  # Check here

    # If step 1 is wrong, add more checkpoints there
    # If step 2 is wrong, investigate step 2
    # Continue bisecting until you find the exact line
```

**Minimal Reproduction:**
```python
# Start with failing case, remove everything non-essential

# Original complex code
def complex_function(user, settings, context, options):
    # 100 lines of code
    ...

# Minimal reproduction
def minimal_test():
    # Just the essentials to reproduce
    data = {"key": "value"}  # Hardcoded minimal input
    result = suspected_function(data)
    assert result == expected  # Fails here
```

### 6. Debug Checklist

```markdown
## Before You Debug
- [ ] Can you reproduce consistently?
- [ ] What's the exact error message?
- [ ] What changed recently?

## During Debugging
- [ ] Read the error message completely
- [ ] Check the stack trace (bottom-up)
- [ ] Verify assumptions with prints/logs
- [ ] Isolate the problem area
- [ ] Test hypothesis with minimal change

## After Fixing
- [ ] Understand WHY it failed
- [ ] Add test to prevent regression
- [ ] Check for similar issues elsewhere
- [ ] Document if non-obvious
```

## Output Format

Provide:
1. Diagnosis of the issue
2. Step-by-step debugging approach
3. Code to add for investigation
4. Likely root cause
5. Fix and prevention strategy