feat: export core Hermes skills

2026-07-15 02:45:56 +00:00
parent a028b63eda
commit 54711fee2a
308 changed files with 41310 additions and 1 deletions
@@ -0,0 +1,91 @@
+---
+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`