renseiai/donmai-kits/python-debugging

Python Debugging

Overview

Debugging Python import errors, type-checker failures, lint failures, and test failures. Systematic diagnosis for the most common Python project failure modes.

Triggers

Use this skill when:

• pytest fails, errors on collection, or hangs
• mypy . reports type errors that block the validate gate
• ruff check . reports lint violations
• ModuleNotFoundError / ImportError at runtime or import time

Debugging Workflow

1. Import / Environment Errors

python -c "import sys; print(sys.executable)"
pip list 2>&1 | head -20

Common root causes:

• Wrong interpreter — confirm you're inside the project's .venv
• Dependency not installed — uv sync / pip install -r requirements.txt
• ModuleNotFoundError for a local package — check pyproject.toml packaging

config / src/ layout vs flat layout

• Editable install missing — pip install -e .

2. Type Errors (validate gate)

mypy . 2>&1 | head -40

Common root causes:

• Missing type hints on public signatures
• Optional[...] not narrowed before use (guard with if x is not None:)
• Missing third-party stubs — install types-* packages

3. Lint (validate gate)

ruff check . 2>&1 | head -40

Most ruff findings are auto-fixable: ruff check --fix ..

4. Test Failures

pytest -q 2>&1 | grep -E "FAILED|ERROR|assert" | head -30

Common root causes:

• Collection errors — an import at module top-level fails (fix imports first)
• Fixture not found — check conftest.py scope/location
• Flaky tests depending on ordering or shared mutable global state

Notes

• uv lives in ~/.local/bin. If uv: not found, prepend ~/.local/bin to

PATH (the installer wrote it there).

• Always operate inside a virtualenv — never install into the system Python.