systematic-debugger
When applying debugging techniques during any investigation — root cause tracing, bisect, defense-in-depth. Enforces hypothesis-first analysis and prohibits guess-and-check changes. Use standalone or inside the debug-issue workflow.
- License 许可
- MIT
- 最近更新
- 2026-11-07
- Stars
- ★ 13
- Forks
- 3
01 前言 Front Matter
- name
- systematic-debugger
- license
- MIT
- description
- When applying debugging techniques during any investigation — root cause tracing, bisect, defense-in-depth. Enforces hypothesis-first analysis and prohibits guess-and-check changes. Use standalone or inside the debug-issue workflow.
03 SKILL.md 正文
Systematic Debugger Skill
Purpose: Stop hallucination loops. Every code change requires a verified hypothesis and a failing test first.
Prohibited Behaviors
- Adding
console.log/print/ debug statements without a stated hypothesis. - Changing code to "see what happens."
- Fixing code before a failing test exists.
- Treating the first hypothesis as confirmed without ruling out alternatives.
Techniques
| Technique | When to use |
|---|---|
| Root Cause Tracing | Follow the call stack up to the originating decision point |
| Defense in Depth | Audit every layer: input validation → business logic → persistence |
| Bisect | Binary-search commits or code paths to find the introduction point |
Required Steps (in order)
- Reproduce the bug reliably. If unable, state why and stop.
- Hypothesize: "The bug is caused by [X] because [evidence Y]."
- List alternatives: at least 2 other hypotheses to rule out.
- Create a failing test that reproduces the bug. Run it — must fail.
- Isolate root cause using a technique above. Rule out alternatives explicitly.
- Fix with minimum code targeting the confirmed root cause only.
- Verify: failing test now passes; full suite has no regressions.
- Log: update
.memory/LESSONS.mdwith root cause + prevention rule.
Common Rationalizations
| Rationalization | Why it's wrong | Do this instead |
|---|---|---|
| "I'll just try changing X and see" | That's the loop we're breaking | State a hypothesis first |
| "The test is hard to write here" | Difficulty ≠ exemption | Document why and get explicit sign-off |
| "I'm pretty sure it's Y" | Pretty sure ≠ confirmed | Rule out alternatives before fixing |
| "I'll add a log to check" | Logs without hypotheses produce noise | State what you expect the log to show first |
Gate: Do not change production code until step 4 (failing test) is complete and step 5 (root cause confirmed) is documented.
04 同仓库更多 Skills
setup-project
When setting up agentskel on a new project that does not yet have .memory/ or .agents/. Use when the user says "set up agentskel", "install agentskel", or "add agent memory to this project".
using-git-worktrees
When running long feature implementations, parallel branch work, or build/test scripts that must not interfere with the user's active working directory. Creates isolated execution environments via git worktrees in sibling directories.
test-engineer
When designing test strategy, analysing coverage, or writing tests outside the TDD cycle. Also use when working with CI pipelines or validating changes end-to-end.
test-driven-development
When implementing logic changes during develop-feature or implement-task. Use the Red-Green-Refactor cycle to write a failing test before any production code.
task-planner
When decomposing a feature or spec into implementable subtasks, estimating scope, or orchestrating multi-step work across subagents.
domain-expert
When working on features that require domain knowledge — business rules, terminology, or invariants specific to this project. [Replace this description and the content below with your project's domain.]