systematic-debugging
Systematic root-cause debugging in 7 step files (0–6) covering TypeScript/Node, Python, and Rust: read errors and build a red-capable feedback loop, trace data flow, analyze patterns, form ranked falsifiable hypotheses, implement one fix via TDD (RED-GREEN-REFACTOR), verify, and guard against rationalizations. Includes language-variant debugger/verify steps (3a/3b/3c, 5a/5b/5c). Observed phrasing: /systematic-debugging, fix this bug, test is failing, performance regression.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- systematic-debugging
- metadata
- { "tags": [ "debugging", "troubleshooting", "problem-solving", "root-cause", "investigation", "tdd", "python", "typescript", "node", "rust", "pdb", "debugpy", "cdp" ], "related_skills": [ "pr-babysit", "issue-worker", "deep-clean" ] }
- description
- Systematic root-cause debugging in 7 step files (0–6) covering TypeScript/Node, Python, and Rust: read errors and build a red-capable feedback loop, trace data flow, analyze patterns, form ranked falsifiable hypotheses, implement one fix via TDD (RED-GREEN-REFACTOR), verify, and guard against rationalizations. Includes language-variant debugger/verify steps (3a/3b/3c, 5a/5b/5c). Observed phrasing: /systematic-debugging, fix this bug, test is failing, performance regression.
- when-to-use
- Use for any technical issue — test failures, production bugs, build or performance problems, integration issues. Also for Python (pdb, debugpy), TypeScript/Node (node inspect, CDP, heap/CPU profiles), and Rust (dbg!, RUST_BACKTRACE, rust-gdb/lldb) debugging. Invoke directly as /systematic-debugging. Do not skip when the issue seems simple, you are in a hurry, or someone wants it fixed NOW — rushing guarantees rework.
- argument-hint
- <issue-or-error> [--phase <1|2|3|4>] [--lang <python|typescript|rust|node>] [--repro <command>]
02 资源文件 17
- 参考文档references/grok/step-0-intake.md2.0 KB
- 参考文档references/grok/step-1-investigate.md5.7 KB
- 参考文档references/grok/step-2-pattern.md1.3 KB
- 参考文档references/grok/step-3-hypothesis.md2.0 KB
- 参考文档references/grok/step-3a-python-debugger.md12.6 KB
- 参考文档references/grok/step-3b-node-debugger.md10.7 KB
- 参考文档references/grok/step-3c-rust-debugger.md3.9 KB
- 参考文档references/grok/step-4-implement.md3.0 KB
- 参考文档references/grok/step-5-verify.md2.4 KB
- 参考文档references/grok/step-5a-python-verify.md940 B
- 参考文档references/grok/step-5b-node-verify.md1.1 KB
- 参考文档references/grok/step-5c-rust-verify.md748 B
- 参考文档references/grok/step-6-guardrails.md7.1 KB
- 参考文档references/hermes/step-0-plan-and-spawn.md3.5 KB
- 参考文档references/hermes/step-1-wait-grok.md1.6 KB
- 参考文档references/hermes/step-2-verify-and-ship.md2.5 KB
- 参考文档references/hermes/step-3-final-report.md790 B
03 SKILL.md 正文
Systematic Debugging
For any technical issue — test failures, production bugs, build or performance problems — find the root cause before touching a fix. This file is the lane identification step only; the working method lives in references/hermes/ and references/grok/.
Global Rules
The lane is determined from a physical signal, not by self-identification. Each agent's launcher stamps a fixed attribution env var into every command it runs; the model cannot set these.
if [[ -n "${HERMES_AGENT:-}" ]]; then echo HERMES
elif [[ -n "${GROK_AGENT:-}" ]]; then echo GROK
else echo UNSET; fi
HERMES→ Hermes lane. Readreferences/hermes/. Stop.GROK→ Grok lane. Readreferences/grok/. Stop.UNSET→ stop and report. Do not guess the lane.
Marker provenance:
- Hermes re-exports
AI_AGENT=hermes-agentandHERMES_AGENT=trueon every command. - Grok Build runs with
GROK_AGENT=1.
Read only the winning lane's references. Do not read the other lane's.
Routing
Hermes lane (Steps 0–3)
| Step | Reference | Purpose |
|---|---|---|
| 0 | references/hermes/step-0-plan-and-spawn.md |
Detect lang; plan the brief (symptom, repro, phase, constraints, acceptance criteria); create the Orca worktree with --agent grok; drop /systematic-debugging <issue-or-error> |
| 1 | references/hermes/step-1-wait-grok.md |
Wait for Grok to finish the pipeline; read its debug summary and commit |
| 2 | references/hermes/step-2-verify-and-ship.md |
Verify the iron law (regression test present), re-run the gate on the clean tree; commit/push/PR as appropriate |
| 3 | references/hermes/step-3-final-report.md |
Final report to the user (root cause, fix, verification, open decisions, commit/PR, worktree teardown) |
Grok lane (Steps 0–6, run by Grok Build)
| Step | Reference | Purpose |
|---|---|---|
| 0. Intake | references/grok/step-0-intake.md |
Symptom statement, target lang, repro command, run state; iron-law gate; invocation. |
| 1. Investigate | references/grok/step-1-investigate.md |
Read errors, build a tight red-capable loop, check recent changes, gather multi-component evidence, trace data flow. |
| 2. Pattern | references/grok/step-2-pattern.md |
Minimize the repro, find working examples, compare against references, identify differences, understand dependencies. |
| 3. Hypothesis | references/grok/step-3-hypothesis.md |
Form 3–5 ranked falsifiable hypotheses; test minimally, one variable at a time; pick the language debugger variant. |
| 3a/3b/3c. Language debugger | step-3a-python-debugger.md, step-3b-node-debugger.md, step-3c-rust-debugger.md |
Python (pdb + debugpy), Node/TS (node inspect + CDP, profiles), Rust (dbg!, RUST_BACKTRACE, rust-gdb/lldb). |
| 4. Implement | references/grok/step-4-implement.md |
TDD cycle: RED failing test, GREEN single fix, per-language verify, REFACTOR; rule of three; question architecture at 3+ failures. |
| 5. Verify & finish | references/grok/step-5-verify.md |
Verification checklist, language cleanup pass (delegates to 5a/5b/5c), guardrails final pass, reporting format. |
| 5a/5b/5c. Language verify | step-5a-python-verify.md, step-5b-node-verify.md, step-5c-rust-verify.md |
Per-language verification + cleanup grep. |
| 6. Guardrails | references/grok/step-6-guardrails.md |
Red-flags list, common-rationalizations table, TDD rationale, TDD cycle detail; cross-cutting rules applied before reporting done. |
04 同仓库更多 Skills
github-workflow
Umbrella for GitHub auth, repo management, issues, PRs, Mergify, and releases. Subsumes github-auth and repo-manager.
brave-automation
baa CLI: Brave profiles, Google sessions, credentials.
aes
AES docs, layers, rule fixes, and legacy migration.
pretext
Build creative browser demos with DOM-free text layout.
popular-web-designs
54 real design systems (Stripe, Linear, Vercel) as HTML/CSS.
p5js
p5.js sketches: gen art, shaders, interactive, 3D.