# Debug

> Systematic approach to debugging errors and unexpected behavior

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

---


# Debug Skill

## Debugging Process

### 1. Reproduce
- Get the exact error message
- Find the minimal steps to trigger it
- Note the environment (Python version, OS, dependencies)

### 2. Locate
- Read the full stack trace (bottom = where it crashed, top = root cause)
- Find the relevant file and line
- Read surrounding code for context

### 3. Understand
- What was the code trying to do?
- What input caused the failure?
- What assumption was violated?

### 4. Fix
- Make the minimal change that fixes the issue
- Don't refactor while debugging
- Add a test that would have caught this

### 5. Verify
- Run the failing case again
- Run the full test suite
- Check for similar patterns elsewhere

## Common Patterns

**NoneType errors**: Something returned None unexpectedly. Check the call chain.

**Import errors**: Missing dependency or circular import. Check requirements and import order.

**Key/Index errors**: Accessing something that doesn't exist. Add existence checks.

**Type errors**: Wrong type passed. Check function signatures and callers.

## Workflow

1. `grep` for the error message in codebase
2. Read the stack trace bottom-to-top
3. Read the failing function
4. Add logging/print if needed to trace values
5. Fix and verify