Debugger (Python)

Why: Runtime bugs — silent failures, wrong variable values, incorrect data flow through complex logic — cannot always be diagnosed from code alone. This skill gives you a real debugger (breakpoints, variable inspection, expression evaluation) instead of scattering print() calls and guessing. You use the Debug Adapter Protocol (DAP) via debugpy to pause execution and inspect actual state.

Hard constraints: Requires debugpy installed (pip install debugpy) and the debugger-core Python package. All commands go through scripts/debug.py. Never leave a debug session running after you are done — always call stop.

When to use

• Runtime errors: A function returns the wrong result and you cannot see why from the source.
• Silent failures: Data is not saved, a callback never fires, but there is no crash or traceback.
• Unexpected values: A variable is None, an empty list, or the wrong type when it should not be.
• Complex data flow: Values pass through multiple functions/classes and you need to see where they go wrong.
• Async / threading bugs: Coroutines or threads produce unexpected interleaving.
• Static analysis is not enough: You have read the code but cannot determine the root cause.

Do not use for: syntax errors, import errors, or type errors that the linter or type checker already catches.

Available commands

All commands run via python scripts/debug.py <action> [args].

Workflows

Interactive debugging (multi-turn)

Use when you need to set multiple breakpoints, step through code, and inspect different variables across turns.

1. start app.py
2. breakpoint app.py 22
3. continue                     # runs until line 22
4. evaluate some_variable       # inspect the value
5. step                         # step to next line
6. variables                    # dump all locals
7. stop                         # always clean up

One-shot probe (single turn)

Use when you have a hypothesis about a specific line and want to see all state at that point in one go.

1. probe app.py:22              # runs to line 22, dumps everything, stops

The probe returns: source context (with >>> marking the line), full stack trace, and all local variables. This is usually enough to confirm or reject a hypothesis.

Code contrast

Anti-pattern: Guess-and-print

# Scattered print() calls that you must add, run, read, and remove.
def process_orders(orders: list[dict]) -> float:
    total = 0.0
    print(f"DEBUG orders: {orders}")           # added for debugging
    for order in orders:
        subtotal = order["quantity"] * order["price"]
        print(f"DEBUG subtotal: {subtotal}")   # added for debugging
        total += subtotal
    print(f"DEBUG total: {total}")             # added for debugging
    return total
# Problems: pollutes code, must remember to clean up, cannot inspect
# complex objects deeply or step through logic interactively.

Top-coder pattern: Probe at the suspect line

$ python scripts/debug.py probe app.py:8

Stopped (breakpoint) at app.py:8
     5 | def process_orders(orders: list[dict]) -> float:
     6 |     total = 0.0
     7 |     for order in orders:
  >>>  8 |         subtotal = order["quantity"] * order["price"]
     9 |         total += subtotal
    10 |     return total

--- Stack Trace ---
#0   process_orders                 (app.py:8)
#1   main                           (app.py:25)

--- Local Variables ---
  total: float = 0.0
  order: dict = {'item': 'Widget', 'quantity': '3', 'price': 9.99}
  orders: list = [{'item': 'Widget', 'quantity': '3', 'price': 9.99}, ...]

# Immediately see: quantity is a string '3', not int 3.
# '3' * 9.99 gives '9.999.999.99' (string repetition), not 29.97.
# Fix the bug, no print() cleanup needed.

Prerequisites

1. Python 3.11+ must be on PATH.
2. debugpy: pip install debugpy
3. debugger-core Python package: pip install -e packages/debugger-core (from the repo root).

Tips

• Probe first. Start with a one-shot probe at the suspicious line. If that gives enough info, you are done.
• Breakpoint before continue. Always set at least one breakpoint before calling continue, or execution will run to completion without stopping.
• Always stop. Call stop when finished. Do not leave zombie debug processes.
• Evaluate rich expressions. evaluate accepts any valid Python expression — e.g. evaluate [o['quantity'] for o in orders], evaluate type(result).__name__.
• Generators and iterators. Evaluate list(gen) to materialise a generator for inspection (note: this consumes it).
• Check the stack. If you are unsure how the code reached a point, use stack to see the full call chain.
• justMyCode is on by default. The debugger skips library internals. If you need to step into a dependency, modify the launch args in the adapter.