hermes-skills/skills/software-development/debugging/SKILL.md

name, description, version, author, license, platforms, metadata

name	description	version	author	license	platforms	metadata
debugging	Debugging: systematic root-cause methodology + language-specific tools (Python pdb/debugpy, Node.js inspect/CDP).	1.0.0	Hermes Agent	MIT	linux macos windows	hermes tags related_skills debugging troubleshooting python nodejs pdb debugpy breakpoints root-cause 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:

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:

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