home / skills / sandraschi / advanced-memory-mcp / python-debugging-expert

python-debugging-expert skill

safe

/skills/technical/python-debugging-expert

This skill helps you diagnose Python issues efficiently using expert debugging playbooks, tools, and best practices for reliable, faster code.

npx playbooks add skill sandraschi/advanced-memory-mcp --skill python-debugging-expert

Review the files below or copy the command above to add this skill to your agents.

Files (10)

SKILL.md

2.1 KB

---
name: python-debugging-expert
description: Master debugger for Python code with expertise in common errors, performance issues, and debugging tools
license: Proprietary
---

# Python Debugging Expert
> **Status**: ✅ Research complete
> **Last validated**: 2025-11-08
> **Confidence**: 🟡 Medium — Research-backed debugging playbook – review semi-annually

## How to use this skill
1. Begin with [modules/core-guidance.md](modules/core-guidance.md) to triage the issue and plan reproduction.
2. Use [modules/diagnostics-and-tooling.md](modules/diagnostics-and-tooling.md) to select appropriate debuggers and tracing tools.
3. Resolve concurrency issues via [modules/async-and-concurrency.md](modules/async-and-concurrency.md).
4. Address hotspots and leaks with [modules/performance-and-memory.md](modules/performance-and-memory.md).
5. Stabilize reproduction pipelines through [modules/testing-and-reproduction.md](modules/testing-and-reproduction.md).
6. Track follow-ups in [modules/known-gaps.md](modules/known-gaps.md) and revisit [modules/research-checklist.md](modules/research-checklist.md) every six months.

## Module overview
- [Core guidance](modules/core-guidance.md) — intake template, triage, communication.
- [Diagnostics & tooling](modules/diagnostics-and-tooling.md) — pdb, debugpy, logging, tracing, IDE features.
- [Async & concurrency](modules/async-and-concurrency.md) — asyncio debugging, race detection, multiprocessing.
- [Performance & memory](modules/performance-and-memory.md) — profiling CPU/memory, GC, leak detection.
- [Testing & reproduction](modules/testing-and-reproduction.md) — fixtures, property-based tests, CI automation.
- [Known gaps](modules/known-gaps.md) — future research.
- [Research checklist](modules/research-checklist.md) — validation cadence.

## Research status
- Updated for Python 3.13 debugging improvements, async task diagnostics, and modern tooling.
- Next review due 2026-05-01 or sooner if CPython introduces major debugging changes.
- Known gaps capture C extension debugging and distributed tracing coverage pending further work.

Overview

This skill is a master debugger for Python code that codifies a repeatable playbook for diagnosing errors, performance issues, and concurrency bugs. It consolidates triage templates, recommended tooling, and focused modules for async, memory, and reproduction workflows. The playbook is kept current with Python releases and recommends a semi-annual review cadence.

How this skill works

The skill guides you through an intake and triage process to capture reproduction steps and scope the problem. It recommends specific diagnostics—pdb, debugpy, logging, tracers, profilers—and hands-on techniques for async and multiprocessing issues. For performance and memory problems it prescribes profiling, GC inspection, and leak detection; for stability it provides testing and CI reproduction patterns. Known gaps and a research checklist help prioritize further investigation.

When to use it

When an intermittent bug lacks reliable reproduction steps.
When CPU or memory hotspots degrade service performance.
When asyncio tasks or multiprocessing code exhibit races or deadlocks.
When you need to instrument code for production tracing and diagnostics.
When building CI tests to capture flaky behavior for future regression detection.

Best practices

Start with a concise intake template: version, environment, minimal reproduction, and observed vs expected behavior.
Reproduce locally with stripped-down cases before adding noisy instrumentation.
Prefer lightweight tracing (structured logs, sampling profilers) in production to avoid overhead.
Use deterministic tests and fixtures to lock down flaky behavior; add property-based tests for edge cases.
Capture async task stacks and use tools that understand event loops and task states.
Document follow-ups and track known gaps for periodic research and tool updates.

Example use cases

Triage and fix an intermittent memory leak in a long-running web service.
Diagnose and resolve deadlocks or race conditions in asyncio-based background workers.
Profile a request handler to reduce tail-latency by identifying CPU hotspots.
Create reproducible CI fixtures to capture a flaky integration test for regression prevention.
Instrument production services with low-overhead tracing to locate a root cause across services.

FAQ

Which debuggers and profilers are recommended?

Use pdb or debugpy for step-debugging; combine logging and structured traces for production. Use cProfile, py-spy, or scalene for CPU; tracemalloc and objgraph for memory analysis.

How often should the playbook be reviewed?

Review the playbook at least every six months or sooner when Python or major tooling introduces relevant changes.