Skip to content
Skills Library
Programming · Building & coding

root-cause

/root-cause

Finds and fixes the actual cause of a bug instead of patching the symptom at the place it was reported. Use when debugging an error, a failing test, a crash, or wrong output, and when a bug report names one caller, page, or input. Traces the failure back to where the bad state originates and fixes it once there.

Repository
vetted ↗
Licence
MIT
Last repository change
07.10.2026

Assessment and security

90/ 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.
Content25 / 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 07.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

Finds and fixes the actual cause of a bug instead of patching the symptom at the place it was reported. Use when debugging an error, a failing test, a crash, or wrong output, and when a bug report names one caller, page, or input. Traces the failure back to where the bad state originates and fixes it once there.

Original author description

Finds and fixes the actual cause of a bug instead of patching the symptom at the place it was reported. Use when debugging an error, a failing test, a crash, or wrong output, and when a bug report names one caller, page, or input. Traces the failure back to where the bad state originates and fixes it once there.

How it works

  1. Loop
  2. Hypotheses, not hunches
  3. Patching the symptom is sometimes right
Original SKILL.md headings · 38 lines, 320 words
SKILL.md preview
---
name: root-cause
description: Finds and fixes the actual cause of a bug instead of patching the symptom at the place it was reported. Use when debugging an error, a failing test, a crash, or wrong output, and when a bug report names one caller, page, or input. Traces the failure back to where the bad state originates and fixes it once there.
license: MIT
---

# Root cause

A bug report describes where the failure showed up, which is rarely where it
started. Patching the reported spot makes that one symptom disappear while the
cause keeps producing others, often in callers nobody has reported yet.

## Loop

1. **Reproduce first.** Get the failure to happen on demand: a failing test, a
   command, a specific input. If you can't reproduce it, say so and gather more
   information before changing code. A fix you can't reproduce is a guess.
2. **Trace backwards.** From the point of failure, follow the bad value to
   where it was produced. Ask "where did this value come from?" until you reach
   the first place where the state was already wrong.
3. **Check the blast radius.** Search for every other caller or path through the
   faulty code. If three callers share one broken function, the fix belongs in
   the function, not in the caller that happened to be reported.
4. **Fix at the source.** Make the change where the bad state originates.
   Prefer one guard in the shared function over one guard per caller.
5. **Prove it.** Re-run the reproduction and show that it now passes. Where the
   project has tests, add one that fails without the fix.

## Hypotheses, not hunches

When the cause isn't obvious, write down your hypothesis and the observation
that would confirm or refute it, then make that observation (a log line, a
debugger step, a narrower test). Change one thing at a time.

If two fixes in a row haven't worked, stop editing. Re-read the error from
scratch and list the assumptions you've been making; one of them is wrong.

## Patching the symptom is sometimes right

Sometimes the source is out of reach, such as a third-party library or another
team's service. Then patch at the boundary, and say explicitly that it's a
workaround, where the real cause lives, and what a proper fix would need.

Versions

The database has no other skills named root-cause.

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

  • 100debugging
    Finds the root cause of an error, failing test, or wrong behaviour, then fixes it with proof. Use when something is broken, a test fails, or output is unexpected.
  • 100principle-fix-root-causes
    Use when fixing a bug or a test that fails unexpectedly: reproduce it first, trace the symptom to its cause, and fix the cause rather than the place the symptom appeared.
  • 100exterminator
    Fixes bugs at the root cause instead of patching the symptom, then hunts down every other place the same bug lives in the codebase. Use this whenever the user reports a bug, error, crash, exception, stack trace, traceback, failing or red test, regression, wrong output, or visual…
  • 100debugging-code
    Finds and fixes the root cause of a bug: pins the symptom, reproduces it, secures a failing test — existing, corrected or new — narrows to the cause with evidence rather than plausibility, measures how far the fix reaches before applying it minimally, and keeps the test as a…
  • 90root-cause-debugging
    Use when diagnosing a bug, failing test, crash, or wrong output. A disciplined, hypothesis-driven method for finding the true root cause from evidence instead of guessing or masking symptoms. Use before writing any fix.
  • 100systematic-debugging
    Diagnoses a reported bug, error, test failure, or unexpected behavior through a 4-phase root-cause analysis before any code changes. Use when the user reports a bug or test failure with an unknown root cause, or invokes /superpowers:systematic-debugging "<symptom>". Not for bugs…

Feedback and reports

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