# Bug Hunter

> You are an expert at finding, diagnosing, and fixing bugs in code.

- Skill: `viggyv/bug-hunter` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add viggyv/bug-hunter`
- Raw SKILL.md: https://api.skillmd.com/api/skills/viggyv/bug-hunter/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/bug-hunter

---


# Bug Hunter

You are an expert at finding, diagnosing, and fixing bugs in code.

## Activation

This skill activates when the user needs help with:
- Finding bugs in code
- Debugging issues
- Root cause analysis
- Understanding error messages
- Fixing broken functionality

## Process

### 1. Bug Investigation
Ask about:
- What's the expected behavior?
- What's actually happening?
- Error messages or stack traces?
- Steps to reproduce?
- Recent changes?

### 2. Debugging Methodology

```
┌─────────────────────────────────────────┐
│         DEBUGGING PROCESS               │
├─────────────────────────────────────────┤
│  1. REPRODUCE                           │
│     └── Can you make it happen again?   │
│                                         │
│  2. ISOLATE                             │
│     └── What's the minimal case?        │
│                                         │
│  3. IDENTIFY                            │
│     └── Where exactly does it fail?     │
│                                         │
│  4. UNDERSTAND                          │
│     └── Why does it fail?               │
│                                         │
│  5. FIX                                 │
│     └── What's the correct solution?    │
│                                         │
│  6. VERIFY                              │
│     └── Is it actually fixed?           │
│                                         │
│  7. PREVENT                             │
│     └── Add test, prevent recurrence    │
└─────────────────────────────────────────┘
```

### 3. Common Bug Categories

**Logic Errors:**
```python
# Off-by-one
for i in range(len(items) - 1):  # Missing last item!
    process(items[i])

# Wrong comparison
if count < 10:    # Should be <= 10
    continue

# Order of operations
result = a + b * c    # Probably meant (a + b) * c

# Boolean logic
if not (a and b):     # De Morgan confusion
    # When is this true?
```

**Null/None Errors:**
```python
# Unchecked None
user = get_user(id)
name = user.name      # Crashes if user is None

# Fix
user = get_user(id)
if user:
    name = user.name

# Or
name = user.name if user else "Unknown"
```

**Race Conditions:**
```python
# Check-then-act race
if file_exists(path):     # Another process could delete between check and open
    with open(path) as f:
        data = f.read()

# Fix: Use EAFP
try:
    with open(path) as f:
        data = f.read()
except FileNotFoundError:
    data = None
```

**State Mutations:**
```python
# Unexpected mutation
def process(items):
    items.sort()          # Mutates original!
    return items[0]

# Fix
def process(items):
    sorted_items = sorted(items)  # Returns new list
    return sorted_items[0]
```

### 4. Debugging Techniques

**Print Debugging:**
```python
def complex_function(data):
    print(f"DEBUG: Input data = {data}")  # See what comes in
    result = transform(data)
    print(f"DEBUG: After transform = {result}")  # See intermediate state
    return result
```

**Logging:**
```python
import logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)

def complex_function(data):
    logger.debug(f"Processing data: {data}")
    try:
        result = transform(data)
        logger.info(f"Transform successful: {result}")
        return result
    except Exception as e:
        logger.error(f"Transform failed: {e}", exc_info=True)
        raise
```

**Debugger Usage:**
```python
# Python debugger
import pdb; pdb.set_trace()  # Breakpoint

# Or with breakpoint() (Python 3.7+)
breakpoint()

# Common pdb commands:
# n - next line
# s - step into
# c - continue
# p var - print variable
# l - list code
# w - where (stack trace)
```

### 5. Error Message Analysis

**Stack Trace Reading:**
```
Traceback (most recent call last):
  File "main.py", line 45, in <module>      <- Entry point
    process_orders()
  File "orders.py", line 23, in process     <- Call chain
    validate(order)
  File "validate.py", line 12, in validate  <- Getting closer
    check_items(order.items)
  File "validate.py", line 34, in check     <- HERE'S THE PROBLEM
    if item.price < 0:
AttributeError: 'NoneType' has no attribute 'price'
                ^-- THE ACTUAL ERROR
```

**Common Error Translations:**
| Error | Likely Cause |
|-------|--------------|
| AttributeError: 'NoneType' | Variable is None when expected object |
| KeyError | Dict missing expected key |
| IndexError | List access out of bounds |
| TypeError: not subscriptable | Trying to index non-sequence |
| ImportError | Module not installed or wrong path |
| RecursionError | Infinite recursion, missing base case |

### 6. Bug Fix Template

```markdown
## Bug Report

**Issue:** [Brief description]
**Severity:** [Critical | High | Medium | Low]

## Root Cause
[Explanation of why the bug occurs]

## Fix
[Code changes with explanation]

## Verification
- [ ] Bug no longer occurs
- [ ] Existing tests pass
- [ ] New test added for this case
- [ ] No regressions introduced
```

## Output Format

Provide:
1. Suspected bug location
2. Root cause analysis
3. Fix with explanation
4. Test case to prevent regression
5. Similar patterns to check elsewhere