debugging-systematically
Use when a test fails, a bug is reported, or observed behavior does not match expectation, and before proposing or applying any fix.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- debugging-systematically
- description
- Use when a test fails, a bug is reported, or observed behavior does not match expectation, and before proposing or applying any fix.
03 SKILL.md 正文
Debugging systematically
A fix you cannot explain is a coincidence. If you cannot name the line that produced the wrong
value and why, do not change anything. This skill owns do I know why; vvkit:verifying-changes
owns did I run it.
Reproduce before theorizing
- Get a deterministic reproduction at the smallest scope that still fails — one test, one input, one path.
- Intermittency is the finding. Once in twenty is almost always ordering, timing or shared state. Record the rate before changing anything; it is how you will know a fix worked.
- A reproduction that resists shrinking: shrink the environment — fewer threads, a fixed seed, one device, one item.
Trace to where it originates
- Walk the wrong value back to where correct input first became wrong output — not where it was observed. The fix belongs in the gap.
- Ask which layer should have rejected this? A nil crashing a view was allowed by the model builder, the parser, and a schema that made the field optional. The defect is where the invariant should have held.
- Fix it there, so the class of bug becomes unrepresentable rather than this instance survivable.
- A toolchain failure no change explains: read the last error in the log, and rule out an exhausted resource first. A full disk surfaces as a corrupt cache or a linker failure.
Instrument every boundary the path crosses
- Across components, each layer looks correct on its own. Log what enters and leaves each boundary, run once; the first with right input and wrong output names the component.
- Configuration too: a variable set in the workflow and absent in the script it launches looks like a logic bug from inside.
One hypothesis, one change
- State it as "X is wrong because Y"; make the smallest change that would falsify it.
- Two changes in one run cannot be attributed, and the useless one stays as a false fix.
- Revert a failed hypothesis's change before forming the next.
A live incident mitigates first
- Production failing now: stop the harm — roll back, flip the flag, shed traffic — as an open decision, undone once the cause is fixed.
- First keep the evidence — logs, a failing request, the bad record — since a rollback erases the reproduction. Label the change as mitigation, then debug against that evidence.
Band-aids are never the fix
| Band-aid | What it costs later |
|---|---|
| A flag that disables the failing path | The path stays broken with two behaviors to reason about; the flag outlives everyone who knew why |
| A special case for the input that failed | The next input in the class fails the same way, and the pattern that names the cause is hidden |
| A guard that swallows the bad state | A crash with a stack trace becomes silently wrong data, further from the cause |
| A sleep or retry over a race | The race now depends on machine speed and returns on faster CI or under load, reading as deliberate |
| Widening a type to accept what broke it | The invariant is deleted instead of enforced; every reader inherits the doubt |
Blocked and must ship a workaround: say it is one, and state the real cause. An unlabelled band-aid is never revisited.
Two failed fixes on one premise
- Two fixes resting on the same assumption fail the same way: write that premise in one sentence and test it before a third fix.
- Three failed fixes is a design finding. When each exposes coupling somewhere new, the structure is wrong; a fourth fix is sunk cost. Take what the attempts revealed and the structural question to the human — restructuring is their decision.
- The human's questions are signals: "is that not happening?" — you assumed; "will it show us…?" — evidence was due first; "stop guessing" — fixes without a cause. Go back to reproducing.
When the cause is outside the code
Timing on shared infrastructure, an external service, a platform defect: write down what was investigated, add handling that fails visibly — a bounded, logged retry, a timeout, a clear error — and logging that catches it next time. Suspect this conclusion: most "no root cause" is an investigation stopped early.
After the fix, harden the path
Make the bad value unreachable: reject it at the entry point, check it where the operation depends on it, refuse the dangerous operation where it must never run — such as a test touching a real directory. Each fails loudly; a guard that swallows is the band-aid above.
Bisect when the trace goes cold
- Bisect the history, the input or the configuration.
- Automate the predicate — a script exiting 0 for good, 1 for bad. Eyeballing misclassifies silently.
- Bisect names the commit that exposed a defect, not always the one that introduced it. Treat it as where to read, not the answer.
- For input, halve the dataset until one record fails alone.
Before you fix
- [ ] The failure reproduces on demand, and you know the rate if it is intermittent
- [ ] You can name the line that produced the wrong value, not just where it surfaced
- [ ] You can name the layer that should have rejected it
- [ ] You can say what the fix breaks if your explanation is wrong
- [ ] A test fails for this reason now and passes after — see
vvkit:writing-tests
04 同仓库更多 Skills
no-heading
Use when proving that the validator rejects a body with no H1 and a force-loading @-link.
wrong-name-does-not-match-dir
Dispatches a subagent per task and reviews between each one.
writing-tests
Use when adding or changing behavior, fixing a bug, or judging whether an existing or generated test earns its place.
writing-skills
Use when authoring or editing a skill, agent, command or hook for this kit, or when deciding whether a piece of guidance belongs in a skill at all.
writing-project-instructions
Use when creating or editing a CLAUDE.md or AGENTS.md, when it has grown long, or when a rule in it also exists in an installed skill.
writing-logs
Use when adding or reviewing log statements, or when deciding what level a message belongs at.