Skip to content
Skills Library
Programming · Analysis

systematic-debugging

/systematic-debugging

Find root causes with evidence, not guesses: reproduce, isolate, hypothesize, test, fix, prevent. Use for bugs, flaky tests, regressions, crashes, wrong output, or 'it works on my machine'.

Licence
MIT
Last repository change
11.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 11.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Find root causes with evidence, not guesses: reproduce, isolate, hypothesize, test, fix, prevent. Use for bugs, flaky tests, regressions, crashes, wrong output, or 'it works on my machine'.

Triggers from the description

it works on my machine
Original author description

Find root causes with evidence, not guesses: reproduce, isolate, hypothesize, test, fix, prevent. Use for bugs, flaky tests, regressions, crashes, wrong output, or 'it works on my machine'.

How it works

  1. Loop
  2. Common root-cause classes (check early)
  3. Flaky tests
  4. Production incidents
  5. Report format
Original SKILL.md headings · 31 lines, 386 words
SKILL.md preview
---
name: systematic-debugging
description: "Find root causes with evidence, not guesses: reproduce, isolate, hypothesize, test, fix, prevent. Use for bugs, flaky tests, regressions, crashes, wrong output, or 'it works on my machine'."
license: MIT
metadata:
  version: "1.0.0"
---

# Systematic debugging

Rule: **no fix without a reproduced failure and an explained cause.** A change that "seems to help" is a guess.

## Loop
1. **Define the failure**: expected vs actual, exact error text, where observed (env, version, input), since when. Get the stack trace/log instead of paraphrasing it.
2. **Reproduce** deterministically; shrink to a minimal failing case (smallest input, fewest dependencies). If intermittent, record frequency and conditions; add logging/seeds rather than retrying until green.
3. **Localize**: bisect the space.
   - `git bisect run <test>` to find the introducing commit.
   - Bisect inputs, config, data, time, dependencies (lockfile diff), environment.
   - Binary-search the call path with assertions/log points; compare a working run with a failing run (diff the traces).
4. **Hypothesize**: write 2-3 candidate causes ranked by likelihood and cost to check. Predict what each would make true that the others would not.
5. **Test the hypothesis** with the cheapest discriminating experiment (log, assert, debugger, unit test). Change one thing at a time. Record results; abandon refuted ideas explicitly.
6. **Fix the cause, not the symptom**: ask "why was this possible?" up to five times; fix at the layer where the invariant was broken.
7. **Prove**: the reproducer now passes; add it as a regression test (failing before, passing after); run the surrounding suite.
8. **Prevent**: add a guard, type, assertion, lint rule, alert or doc so the class of bug cannot return silently.

## Common root-cause classes (check early)
Off-by-one/boundaries - null/empty/unicode/timezone/locale - stale cache or state - race/ordering/async not awaited - shared mutable state - resource leak/pool exhaustion - config/env drift (flags, secrets, versions) - floating point/overflow/encoding - network timeouts/retries/partial failure - wrong assumption about a library's contract (read the source/docs).

## Flaky tests
Never add blind retries or sleeps. Look for: shared state between tests, time/random dependence, ordering, real network/IO, port collisions, async without proper awaiting, resource cleanup. Make it fail on demand (run in loop, shuffle order, constrain CPU) before fixing.

## Production incidents
Stabilize first (rollback, flag off, scale), preserve evidence (logs, heap/thread dumps, metrics window) then debug on a copy. Hand the timeline to `sre-engineer` for the post-mortem.

## Report format
`Symptom - Reproduction - Root cause (evidence) - Fix (diff) - Regression test - Prevention - Not verified`.
Be explicit about what you could not reproduce or confirm.

Versions

RepositoryScoreLicence
This page · swap-cameroon/kuro-antigravity-config100MIT
magnus919/agent-skills100MIT
FrancoStino/opencode-skills-collection100MIT
foryourhealth111-pixel/Vibe-Skills100Apache-2.0
GanyuanRan/Aegis100MIT
rootcastleco/rei-skills100MIT
jkaloger/lazyspec100MIT
innei/ryugi100MIT
yusixian/anjian100MIT

Database snapshot: 13.11.2026 · package version 27e2ffd3a531 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90debugging
    Systematic root-cause debugging: reproduce, investigate, hypothesize, fix with verification. Use when asked to "debug this", "fix this bug", "why is this failing", "troubleshoot", or mentions errors, stack traces, broken tests, flaky tests, regressions, or unexpected behavior.
  • 100debugging
    Systematic debugging by root cause analysis. Use when facing a bug, test failure, flaky behavior, production error, or integration failure. Covers reproduce, hypothesize, fix, prevent, and post-mortems.
  • 90debugging-root-cause
    Use to reproduce failures, gather evidence, test hypotheses, isolate faults across system boundaries, and identify evidence-supported root causes.
  • 90debug
    Debug a failing command, bug, flake, runtime error, wrong output, or performance regression with evidence: reproduce, minimize, hypothesize, instrument, fix, and regression-test. Use when the user asks to debug, diagnose, fix a failure, or use debug-loop.
  • 100debug
    Systematic root-cause debugging — reproduce, isolate, hypothesize, fix with TDD. Use when: bug, error, fix, broken, crash, exception, not working, unexpected behavior, regression.
  • 100debugging-specialist
    Diagnoses defects with a hypothesis-driven method: reproduce, isolate, form falsifiable hypotheses, test them with evidence, fix the root cause with a failing test first. Use for bugs, failing tests and unexpected behaviour.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.