Systematic debugging
Portable playbook for coding agents: always-on principles, user rules, and triggered skills.
npx -y skills add Tsurai7/agentic-playbook --skill systematic-debuggingAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Systematic root-cause debugging: investigate before fixing, log hypotheses, trace data flow, and stop to reassess after 3 failed fix attempts. Use when debugging a non-obvious failure, when a fix attempt did not work, or when asked to find a root cause. Skip for trivial errors whose cause is stated in the error message.
SKILL.md
2.1 KB, as published. Nobody here has run it
Systematic debugging
The Iron Law
No fixes without investigation. Reproduce the failure first, read the actual error (not what you assume it says), and locate the failing layer before editing anything. A fix that skips investigation is a guess.
Hypothesis loop
Before each probe, write one line:
HYPOTHESIS: <what you believe is wrong and why> → TEST: <cheapest observation that can falsify it>.
Run the test — a log line, an assertion, a targeted read — and record what it
ruled out. If the hypothesis is wrong, don't guess again blind — return to
gathering evidence.
Trace the data, not the blame
Follow the value through the layers it passes through (input → transform → output) until you find the first place reality diverges from expectation. Fix at the divergence point, not at the symptom. A fix proposed before tracing the data flow is a guess, not a diagnosis.
The 3-strikes stop rule
After 3 failed fix attempts — three HYPOTHESIS lines whose fixes did not
survive their test — STOP. Do not try variant #4 of the same idea.
Re-read the evidence, list what every failed attempt assumed in common, and
question that shared assumption — it is usually a wrong architectural belief, not a
string of bad luck. Escalate or ask the user rather than continuing to guess.
Exit criteria
A fix ships only with the reproducing check that now passes — see
verification-before-completion for the evidence bar before claiming done.
Provenance
Distilled from the gstack /investigate skill by Garry Tan
(garrytan/gstack, MIT) — method only,
none of the gstack runtime (no telemetry, gbrain, or scope-freeze tooling
carried over).