# Python Automated Debugging

> Use when fixing a Python test that has failed multiple attempts, when print-debugging hasn't revealed the issue, or when you need to investigate runtime state systematically

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

---


# Python Automated Debugging

## Overview

**Run the debugger. Don't just plan to run it.**

This skill uses `debug_session.py` to run non-interactive pdb sessions. You specify commands upfront, execute, analyze output, then iterate. Works on macOS/Linux only.

## When to Use

- Test has failed 2+ times despite your fixes
- Code looks correct but behaves wrong
- You need to see runtime state, not just read code
- Print statements haven't revealed the issue

## The Cycle

```dot
digraph debug_cycle {
    rankdir=LR;
    "Form Hypothesis" -> "Write pdb commands";
    "Write pdb commands" -> "RUN debug_session.py";
    "RUN debug_session.py" -> "Analyze output";
    "Analyze output" -> "Hypothesis confirmed?" [style=invis];
    "Hypothesis confirmed?" [shape=diamond];
    "Hypothesis confirmed?" -> "Fix bug" [label="yes"];
    "Hypothesis confirmed?" -> "Form Hypothesis" [label="no - new hypothesis"];
}
```

**You MUST actually execute the tool.** Planning what you would run is not debugging.

## Tool Usage

Location: `debug_session.py` in this skill's directory.

```bash
# Basic usage
python debug_session.py <script.py> "cmd1" "cmd2" ... "q"

# Debug a module
python debug_session.py -m <module> "cmd1" "cmd2" "q"

# Save output
python debug_session.py <script.py> "cmd1" "cmd2" "q" --output debug.log
```

**Always end with `q`** to quit cleanly and avoid hanging.

## Example Sessions

**Investigate a caching bug:**
```bash
python debug_session.py test_file.py \
    "b process_item" \
    "c" \
    "p multiplier" \
    "p self.cache" \
    "c" \
    "p multiplier" \
    "p self.cache" \
    "q"
```
Hypothesis: cache isn't updating. Commands compare state across two calls.

**Trace unexpected None return:**
```bash
python debug_session.py buggy.py \
    "b compute_result" \
    "c" \
    "a" \
    "n" \
    "n" \
    "p intermediate" \
    "p result" \
    "w" \
    "q"
```
Hypothesis: intermediate calculation fails. Commands trace through function.

**Debug exception origin:**
```bash
python debug_session.py crash.py \
    "c" \
    "w" \
    "pp locals()" \
    "l" \
    "q"
```
Let it crash, then inspect stack and locals at crash point.

## Iteration Is Expected

Your first debug run rarely gives complete answers. Common pattern:

1. **Run 1**: Set breakpoint, print obvious variables → discover which variable is wrong
2. **Run 2**: Trace where that variable gets set → discover it's cached
3. **Run 3**: Inspect cache behavior across calls → find the bug

Each run narrows the search space. **Don't repeat the same debug session** - each iteration should test a new hypothesis or investigate what you learned from the previous run.

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Planning commands but not running them | Execute debug_session.py immediately |
| Repeating the same debug session | Each run should test a different hypothesis |
| One massive debug session | Multiple focused sessions, each testing one hypothesis |
| Forgetting `q` at the end | Always end with `q` to avoid hanging |
| Debugging without a hypothesis | State what you expect to find BEFORE running |

## Red Flags - You're Not Actually Debugging

- "I would run..." → Run it now
- "The commands I'd use are..." → Execute them
- "Based on reading the code..." → You need runtime data, not code reading
- Repeating the same session hoping for different results → New hypothesis needed

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