Add software-development/debugging
This commit is contained in:
@@ -0,0 +1,182 @@
|
||||
---
|
||||
name: debugging
|
||||
description: "Debugging methodology and tools: systematic root-cause analysis, Python pdb/debugpy, Node.js inspect/CDP, Hermes TUI slash commands."
|
||||
version: 2.0.0
|
||||
author: Hermes Agent
|
||||
license: MIT
|
||||
platforms: [linux, macos, windows]
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [debugging, troubleshooting, root-cause, pdb, debugpy, node-inspect, cdp, hermes-tui]
|
||||
related_skills: [test-driven-development, writing-plans]
|
||||
---
|
||||
|
||||
# Debugging — Methodology & Tools
|
||||
|
||||
Four-layer debugging: systematic root-cause methodology first, then language-specific tooling for Python (pdb/debugpy), Node.js (inspect/CDP), and Hermes TUI slash commands.
|
||||
|
||||
## Section 1: Systematic Debugging (Methodology)
|
||||
|
||||
**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
|
||||
|
||||
### The Four Phases
|
||||
|
||||
**Phase 1: Root Cause Investigation**
|
||||
1. Read error messages carefully — they often contain the exact solution
|
||||
2. Reproduce consistently — can you trigger it reliably?
|
||||
3. Check recent changes — `git log --oneline -10`, `git diff`
|
||||
4. Gather evidence in multi-component systems — log at each boundary
|
||||
5. Trace data flow — where does the bad value originate?
|
||||
|
||||
**Phase 2: Pattern Analysis**
|
||||
1. Find working examples in the same codebase
|
||||
2. Compare against reference implementations
|
||||
3. Identify every difference between working and broken
|
||||
4. Map dependencies and assumptions
|
||||
|
||||
**Phase 3: Hypothesis and Testing**
|
||||
1. Form a SINGLE hypothesis: "I think X is the root cause because Y"
|
||||
2. Make the SMALLEST possible change to test it
|
||||
3. Verify BEFORE continuing — did it work?
|
||||
|
||||
**Phase 4: Implementation**
|
||||
1. Create failing test case first (RED)
|
||||
2. Implement single fix addressing root cause (GREEN)
|
||||
3. Verify fix with full test suite
|
||||
4. If fix doesn't work: Rule of Three — after 3 failed fixes, question the architecture
|
||||
|
||||
### Iron Law
|
||||
```
|
||||
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
|
||||
```
|
||||
|
||||
### Red Flags — Stop and Follow Process
|
||||
- "Quick fix for now, investigate later"
|
||||
- "Just try changing X and see if it works"
|
||||
- "One more fix attempt" (after 2+ failures)
|
||||
- Each fix reveals a new problem in a different place
|
||||
|
||||
See `references/systematic-debugging.md` for the full methodology with rationalizations table and Hermes tool integration patterns.
|
||||
|
||||
---
|
||||
|
||||
## Section 2: Python Debugging (pdb + debugpy)
|
||||
|
||||
### Quick Reference: When to Use What
|
||||
|
||||
| Tool | When |
|
||||
|---|---|
|
||||
| `breakpoint()` + pdb | Local, interactive, simplest |
|
||||
| `python -m pdb` | Launch existing script under pdb, no source edits |
|
||||
| `debugpy` | Remote/headless/attach to running process (DAP protocol) |
|
||||
| `remote-pdb` | Cleanest agent-friendly remote pdb over TCP |
|
||||
|
||||
### pdb Inside the REPL
|
||||
|
||||
| Command | Action |
|
||||
|---|---|
|
||||
| `n` | next line (step over) |
|
||||
| `s` | step into |
|
||||
| `c` | continue |
|
||||
| `b file:line` | set breakpoint |
|
||||
| `p expr` / `pp expr` | print / pretty-print |
|
||||
| `w` | where (stack trace) |
|
||||
| `!stmt` | execute arbitrary Python |
|
||||
| `interact` | full Python REPL in current scope |
|
||||
|
||||
### Debugging pytest
|
||||
```bash
|
||||
pytest tests/test_foo.py::test_bar --pdb -p no:xdist # xdist breaks pdb
|
||||
```
|
||||
|
||||
### Remote Debug with debugpy
|
||||
```python
|
||||
import debugpy
|
||||
debugpy.listen(("127.0.0.1", 5678))
|
||||
debugpy.wait_for_client() # blocks until IDE attaches
|
||||
```
|
||||
|
||||
### Remote Debug with remote-pdb (simpler)
|
||||
```python
|
||||
from remote_pdb import set_trace
|
||||
set_trace(host="127.0.0.1", port=4444) # then: nc 127.0.0.1 4444
|
||||
```
|
||||
|
||||
### Key Pitfalls
|
||||
- pdb under pytest-xdist silently hangs — always use `-p no:xdist`
|
||||
- `breakpoint()` in CI/non-TTY hangs — never commit it
|
||||
- `PYTHONBREAKPOINT=0` disables all breakpoint() calls
|
||||
- debugpy.listen only blocks if wait_for_client() is also called
|
||||
- ptrace_scope=1 (Ubuntu default) may block attach-to-PID
|
||||
|
||||
See `references/python-debugpy.md` for full recipes (post-mortem, Hermes subprocess debugging, one-shot patterns).
|
||||
|
||||
---
|
||||
|
||||
## Section 3: Node.js Debugging (inspect + CDP)
|
||||
|
||||
### Quick Reference
|
||||
|
||||
| Tool | When |
|
||||
|---|---|
|
||||
| `node inspect` | Built-in CLI REPL, quick poking |
|
||||
| `ndb` / CDP via `chrome-remote-interface` | Scriptable automation, many breakpoints |
|
||||
|
||||
### Launch and Attach
|
||||
```bash
|
||||
node --inspect-brk script.js # pause on first line
|
||||
node inspect -p <pid> # attach to running process
|
||||
kill -SIGUSR1 <pid> # enable inspector on existing process
|
||||
```
|
||||
|
||||
### The `debug>` REPL
|
||||
- `sb('file.js', 42)` — set breakpoint
|
||||
- `cont` / `next` / `step` / `out` — navigate
|
||||
- `repl` — drop into JS REPL in paused scope
|
||||
- `bt` — backtrace
|
||||
- `exec expr` — evaluate once
|
||||
|
||||
### Debugging Hermes ui-tui
|
||||
```bash
|
||||
# Build first, then debug the built output
|
||||
cd ui-tui && npm run build
|
||||
node --inspect-brk dist/entry.js
|
||||
# In another terminal: node inspect -p <pid>
|
||||
```
|
||||
|
||||
### Key Pitfalls
|
||||
- `node inspect` CLI does NOT follow TypeScript sourcemaps — break in built `dist/*.js`
|
||||
- `--inspect` vs `--inspect-brk`: former doesn't pause, your breakpoints may race
|
||||
- Port 9229 is default; use `--inspect=0` for random port when multiple processes
|
||||
- `--inspect` on parent does NOT inspect children — use `NODE_OPTIONS='--inspect-brk'`
|
||||
|
||||
See `references/node-inspect-debugger.md` for CDP scripting, heap snapshots, CPU profiles, and Vitest debugging.
|
||||
|
||||
---
|
||||
|
||||
## Section 4: Debugging Hermes TUI Slash Commands
|
||||
|
||||
Hermes slash commands span three layers:
|
||||
```
|
||||
Python backend (hermes_cli/commands.py) ← COMMAND_REGISTRY
|
||||
│
|
||||
TUI gateway (tui_gateway/server.py) ← slash.exec / command.dispatch
|
||||
│
|
||||
TUI frontend (ui-tui/src/app/slash/) ← local handlers + fallthrough
|
||||
```
|
||||
|
||||
### Common Issues
|
||||
1. **Command in TUI but not autocomplete** → missing from `COMMAND_REGISTRY` in `commands.py`
|
||||
2. **Command in autocomplete but doesn't work** → check both gateway handler and TUI local handler
|
||||
3. **Behavior differs CLI vs TUI** → different implementations exist; check both
|
||||
4. **Config persists but UI doesn't update** → need `patchUiState(...)` alongside `config.set`
|
||||
5. **Gateway silently ignores** → command not in `GATEWAY_KNOWN_COMMANDS` or is `cli_only`
|
||||
|
||||
### Investigation Steps
|
||||
```bash
|
||||
search_files --pattern "/commandname" --file_glob "*.ts" --path ui-tui/
|
||||
search_files --pattern "commandname" --path hermes_cli/commands.py
|
||||
search_files --pattern "complete.slash|slash.exec" --path tui_gateway/
|
||||
```
|
||||
|
||||
See `references/debugging-hermes-tui-commands.md` for the full investigation guide, fix patterns, and verification checklist.
|
||||
Reference in New Issue
Block a user