Skip to content
Skills Library
Programming · Analysis

systematic-debug

/systematic-debug

Use for bugs whose cause is not localizable — intermittent or flaky failures, "works on my machine", regressions with no stack trace, heisenbugs, wrong results with no error. Hypothesis-driven, one variable at a time.

Licence
MIT
Last repository change
05.10.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 05.10.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

Use for bugs whose cause is not localizable — intermittent or flaky failures, "works on my machine", regressions with no stack trace, heisenbugs, wrong results with no error. Hypothesis-driven, one variable at a time.

Triggers from the description

works on my machine

Arguments

/systematic-debug [symptom, when it happens, what changed recently]
Original author description

Use for bugs whose cause is not localizable — intermittent or flaky failures, "works on my machine", regressions with no stack trace, heisenbugs, wrong results with no error. Hypothesis-driven, one variable at a time.

How it works

  1. Output
Original SKILL.md headings · 21 lines, 245 words
SKILL.md preview
---
name: systematic-debug
description: Use for bugs whose cause is not localizable — intermittent or flaky failures, "works on my machine", regressions with no stack trace, heisenbugs, wrong results with no error. Hypothesis-driven, one variable at a time.
allowed-tools: Read, Grep, Glob, Bash, Edit, Write
when_to_use: Use automatically when bug-fix cannot name a suspect file from the evidence, or after one fix attempt did not hold.
argument-hint: "[symptom, when it happens, what changed recently]"
effort: high
---

# systematic-debug

The bug-fix skill assumes the evidence points at a file. This one is for when it does not — guessing and patching is how a flaky bug becomes two.

1. REPRODUCE: find a command that shows the failure, and its rate (e.g. 3/20 runs). No reproduction → gather evidence first (logs, timestamps, inputs, environment diff); never fix what you cannot observe.
2. BISECT the change: last known good vs first known bad — `git bisect run <repro>` when history is the variable, halving the input when data is, toggling config/env one key at a time when the environment is.
3. HYPOTHESIS LOG: one hypothesis per attempt, the observation that would falsify it, the result. Change one variable per run. Two falsified in a row → widen the evidence, don't narrow the guess.
4. FIX at the proven cause only, then rerun the reproduction enough times to beat the observed failure rate. Add the reproduction as a regression test.
5. Race, timing or ordering cause → name the shared state and the missing ordering (lock, await, idempotency, transaction); a sleep or retry is not a fix.
6. Guarded area implicated (auth, payment, schema, CI) → stop and escalate per HARD STOPS with the log so far.

## Output

```text
REPRO: [command] — [failure rate before → after]
CAUSE: [proven cause] — [the evidence that proved it]
LOG: H1 [..] ✗ · H2 [..] ✓
FIX: [file:line — what changed] | TEST: [regression test]
```

Versions

RepositoryScoreLicence
This page · mtvrkan/senior-dev-kit100MIT
xoai/sage100MIT
xbklairith/kisune100MIT
skymanbp/cc-enforcer90MIT
lucasouzadev/agent-kit-skill86MIT

Database snapshot: 13.11.2026 · package version 0a74b08954e8 (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

  • 100root-cause-analysis
    Performs systematic root cause analysis to identify the true source of bugs, errors, and unexpected behavior through structured investigation phases — not just treating symptoms. Use when a user reports a bug, crash, error, or broken behavior and needs to debug, troubleshoot, or…
  • 95debugging
    Use when debugging bugs, test failures, or unexpected behavior. Triggers: 'why isn't this working', 'this doesn't work', 'X is broken', 'something's wrong', 'getting an error', 'exception in', 'stopped working', 'regression', 'crash', 'hang', 'flaky test', 'intermittent…
  • 100systematic-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'.
  • 100debugging
    Diagnoses and fixes software bugs, test failures, regressions, flaky tests and slowdowns. Use when something throws, crashes, returns wrong output, fails a test or build, is flaky or newly slow, the user asks why something happens, or a first fix attempt did not work, including…
  • 100systematic-debugging
    Use when diagnosing bugs, failing tests, build failures, unexpected behavior, flaky tests, regressions, or production incidents. Requires reproduction, root cause evidence, one-hypothesis fixes, and regression verification before editing.
  • 100debugging
    Finds and fixes bugs through systematic root cause analysis, stack trace interpretation, browser DevTools automation, CI/CD pipeline debugging, performance profiling, test pollution detection, and AI-powered error analysis. Use when the user asks to debug, fix a bug, investigate…

Feedback and reports

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