92 lines
3.6 KiB
Markdown
92 lines
3.6 KiB
Markdown
---
|
|
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`
|