| name | systematic-debugging |
| description | Root-cause-first debugging loop for code or runtime errors: understand
the failure before proposing a fix. Adapted from Hermes' systematic-
debugging — same iron law, smaller surface, SoulClaw-tool-aware.
|
| version | 0.1.0 |
| tags | ["coding","debugging"] |
| metadata | {"soulclaw":{"category":"coding","triggers":["报错","这个 bug","修一下","debug","调试","root cause","traceback","exception"],"capabilities":[],"related_skills":["task-planning","skill-authoring"]}} |
systematic-debugging
Trigger
Use this skill when the user reports a bug, a failing test, an
unexplained runtime exception, a flaky job, or pastes a traceback.
Do NOT use this when:
- The user only wants a code review of working code.
- The error is obviously environmental (missing env var) and the fix
is one line.
- The user explicitly says "just patch it, don't investigate".
The Iron Law
No fix without a root cause. A symptom fix is failure. If you
haven't completed Phase 1, you cannot propose a fix.
Inputs
symptom: the user-visible failure (error message, wrong output,
hang, ...). Capture verbatim.repro: how to reproduce. Ask if missing.recent_changes: what changed since it last worked.scope: file paths / functions / cron jobs / channels involved.
Steps
Phase 1 — Understand:
- Restate the symptom in your own words. If you can't, ask.
- Reproduce or get the user to reproduce. No repro = no fix.
- Read the smallest necessary code with
read_file. Avoid wide grep.
- State the hypothesis as: "Failure happens because X, evidenced by Y".
Phase 2 — Localise:
5. Add minimal logging or a targeted test that would prove / disprove
the hypothesis.
6. Run it (or have the user run it) and read the new evidence.
Phase 3 — Fix:
7. Propose the smallest change that addresses the root cause. Show the
diff. State which assumption it corrects.
8. Verify with the same repro / test you used in Phase 2.
Phase 4 — Land:
9. State what regression test was added (or why none was needed).
10. Note any related-but-not-fixed issues; do not silently widen scope.
Verification
- The fix reverts a specific named cause, not a generic "improvement".
- The repro that failed before the fix passes after.
- Tests that already passed still pass.
- Changes are minimal — no drive-by edits, no comment churn.
Failure Signals
- "Try this and see if it works" without a hypothesis.
- Multiple unrelated changes in one fix.
- The user has to debug your fix.
- Same bug class re-fires within a week.
