# Debug

> Systematic approach to debugging errors and unexpected behavior Use when this capability is needed.

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

---


# 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

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/victordibia) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->