Skip to content
Skills Library
Programming · Analysis

debug

/debug

Find the root cause of a bug before you fix it. Read this skill before you fix any bug. Read it also when the fix looks obvious. Use it when the user says "fix", "broken", "not working", "error", "failing", or "bug". Use it also when a test fails unexpectedly during other work.

Repository
skills ↗
Licence
MIT
Last repository change
16.10.2026

Assessment and security

92/ 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.
Content27 / 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
3
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 16.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

Find the root cause of a bug before you fix it. Read this skill before you fix any bug. Read it also when the fix looks obvious. Use it when the user says "fix", "broken", "not working", "error", "failing", or "bug". Use it also when a test fails unexpectedly during other work.

Triggers from the description

fixbrokennot workingerrorfailingbug
Original author description

Find the root cause of a bug before you fix it. Read this skill before you fix any bug. Read it also when the fix looks obvious. Use it when the user says "fix", "broken", "not working", "error", "failing", or "bug". Use it also when a test fails unexpectedly during other work.

How it works

SKILL.md has no level-two headings · 22 lines, 677 words

SKILL.md preview
---
name: debug
description: Find the root cause of a bug before you fix it. Read this skill before you fix any bug. Read it also when the fix looks obvious. Use it when the user says "fix", "broken", "not working", "error", "failing", or "bug". Use it also when a test fails unexpectedly during other work.
---

Do not fix a bug before you know its root cause. The search starts at the symptom, but it does not end there.

Fast path: when the error output shows the first cause directly, skip the hypothesis steps. An example is a stack line that points at the cause. Do not skip the reproduction, the regression test, or the `verify` skill in step 8. If the visible fix does not make the reproduction pass on the first try, the cause was not visible. Then do all the steps.

1. Before you reproduce the bug, create a task list with these steps as its items. If a task list already exists, add the steps to it. Each step is one item. When you skip a step, mark it done and add `skip: <reason>` to its text. The fast path skips the hypothesis steps this way. To go back to an earlier step, add that step and each step after it again as new items. Then delete the unfinished items that the new items replace.
2. Reproduce the bug first. Build the smallest reproduction that fails every time. If you cannot reproduce the bug, collect evidence until you can: logs, inputs, and versions. Do not guess.
3. Read the actual error. Find the first cause in the chain of causes, not the nearest symptom.
4. Make one hypothesis. Write it with the observation that would confirm it or refute it. Get that observation before you start a fix: a log line, an assertion, or a probe. If the evidence does not exist yet, add instrumentation. Keep the instrumentation small and easy to remove, and remove it when it has given its answer.
5. When two hypotheses compete, design one observation that shows which one is true. Do not try fixes one after another.
6. Fix the root cause, one fix at a time. Flag another problem that you find, such as a second bug, but do not fix it. Dead code is not another problem. Before the fix, delete the dead code in each file that the fix changes, as `implement` does. Do this also when the bug did not touch that code. Dead code is functions, imports, and parameters that no caller uses, and branches that no caller reaches. It is also stale flags, and validators that repeat a check that a boundary already did. It is also comments that repeat the code or excuse a workaround. Keep dead code that a non-goal puts out of scope. Read [fix root causes](references/fix-root-causes.md) before a fix that adds a guard, a catch, or a comment that defends it. Read it also when the same cause can occur elsewhere, or when the failure shows only after a restart.
7. Add the regression test that would have caught this bug. It fails on the old code and passes with the fix.
8. Before you report the fix, read the `verify` skill and follow it. Your report claims that the bug is fixed, and `verify` proves that claim. When the bug appeared inside a slice, the full gate waits for the slice's commit.

Rules:

- Do not try several fixes at random to see if one helps.
- Stop the loop after three refuted hypotheses in a row. Stop it also when the available evidence cannot give a reproduction. Then report what you tried and which observation is missing, and let the user decide.
- If the fix does not make the reproduction pass, the hypothesis was wrong. Go back to step 4. Do not keep the failed fix and add a second fix. When two failed fixes shared one premise, read [attack the premise](references/attack-the-premise.md).
- If the root cause shows a design problem, say so. Offer to run `drill` on the redesign. Do not hide the problem under a workaround.
- When the cause took more than one hypothesis to find, propose a cheap signal that stays on. It is a log line, a metric, or an assertion that would have shown this cause at once. Add it when the user agrees.
Files in this package (3)
  • SKILL.md 4 KB
  • references/attack-the-premise.md 2 KB
  • references/fix-root-causes.md 2 KB

Versions

RepositoryScoreLicence
This page · pwguler/skills92MIT
ericrisco/rsc-harness100MIT
nicsuzor/academicops100MIT
duronext/jig100MIT
drosam/agents100MIT
rizukirr/vibekit100MIT
DingyangLyu/MatClaw100Apache-2.0
Kanevry/session-orchestrator100MIT
kdlbs/kandev100AGPL-3.0

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

  • 100hatch3r-bug-fix
    Step-by-step bug fix workflow. Diagnose root cause, implement minimal fix, write regression test. Use when fixing bugs, working on bug report issues, or when the user mentions a bug.
  • 100debug-failure
    Find the root cause of an error, crash, failing test, regression or wrong behaviour, then fix it with a regression test. Use this whenever something is broken or behaves unexpectedly and the cause is not already proven, even if a fix seems obvious. Do not guess at fixes.
  • 100systematic-debugging
    Find the root cause of a bug, test failure, crash or unexpected behaviour before changing any code. Use this whenever something does not work as expected, a test fails, an error appears, or an earlier fix did not hold, even when the cause looks obvious, because the obvious cause is often a symptom.
  • 90debug-to-root-cause
    Use whenever something is broken, flaky, or behaving unexpectedly — find the root cause systematically (reproduce, isolate, hypothesize, verify) and fix the cause, not the symptom. Never shotgun-edit.
  • 100sdlc-debug
    Bug track: reproduce, find the root cause with evidence, write a failing regression test, apply the smallest fix, check siblings, verify on the real surface. Use when something behaves wrongly, a test fails, an error is reported, or the user says 'debug', 'fix this bug' or 'why does X happen'.
  • 100systematic-debug
    Finds the root cause of a bug before any fix is written, including failures that cross component boundaries. Use when the user says debug, broken, failing, flaky, or root cause, pastes a stack trace or error log, or tests fail unexpectedly.

Feedback and reports

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