---
name: debugging
description: "Debugging: systematic root-cause methodology + language-specific tools (Python pdb/debugpy, Node.js inspect/CDP)."
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [debugging, troubleshooting, python, nodejs, pdb, debugpy, breakpoints, root-cause]
    related_skills: [test-driven-development]
---

# Debugging — Methodology + Tools

Complete debugging guidance: the systematic process for finding root causes, plus language-specific tool references for Python and Node.js.

## The Iron Law

```
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
```

Random fixes waste time and create new bugs. Quick patches mask underlying issues.

## The Four Phases

1. **Root Cause Investigation** — Read errors carefully, reproduce consistently, check recent changes, gather evidence at component boundaries, trace data flow upstream, verify hypothesis against ALL known facts
2. **Pattern Analysis** — Find working examples, compare against references, identify differences
3. **Hypothesis and Testing** — Form single hypothesis, test minimally (one variable at a time), verify before continuing
4. **Implementation** — Create failing test, implement single fix, verify, check for regressions

### Rule of Three
If 3+ fix attempts fail, STOP and question the architecture. Don't attempt fix #4 without discussion.

See `references/methodology.md` for the complete systematic debugging process with red flags, rationalizations table, and Hermes tool integration.

## Language-Specific Tools

### Python (pdb + debugpy)

| Tool | When |
|------|------|
| `breakpoint()` + pdb | Local, interactive, simplest |
| `python -m pdb script.py` | Launch existing script under pdb, no source edits |
| `debugpy` | Remote/headless, attach to running process, DAP protocol |
| `remote-pdb` | Terminal-agent-friendly remote debugging via netcat |

**Quick recipe:**
```python
def compute(x, y):
    breakpoint()  # drops into pdb here
    return x + y
```

See `references/python-debugpy.md` for full pdb command reference, debugpy remote patterns, post-mortem debugging, pytest integration, and Hermes-specific process debugging.

### Node.js (inspect + CDP)

| Tool | When |
|------|------|
| `node inspect script.js` | Built-in CLI REPL, zero install |
| `node --inspect-brk` | Start with inspector, pause on first line |
| `chrome-remote-interface` | Scriptable CDP automation |

**Quick recipe:**
```bash
node --inspect-brk script.js &
node inspect -p $!
# debug> sb('script.js', 42)
# debug> cont
# debug> repl  # inspect locals
```

See `references/node-inspect.md` for full REPL commands, attaching to running processes, CDP driver scripts, heap snapshots, CPU profiles, and Hermes ui-tui debugging.

## When to Use Breakpoint Debugging vs Print Statements

- `print()`/`logging.debug` solves it in under a minute → use prints
- `pytest -vv --tb=long --showlocals` reveals the issue → use pytest output
- Need to see intermediate state in a closure → use breakpoints
- Long-running process misbehaves and can't be restarted → use remote attach
- Need call-stack context at the crash site → use post-mortem

## Common Pitfalls

- **pdb under pytest-xdist silently does nothing** — always use `-p no:xdist`
- **`breakpoint()` in committed code** — add pre-commit grep as safety net
- **Wrong line numbers in TS** — breakpoints hit emitted JS, not source TS
- **`--inspect` vs `--inspect-brk`** — without `-brk`, script races past your breakpoint
- **Port collisions** — use `--inspect=0` for random port, read from `/json/list`