Skip to content
Skills Library
Programming · Analysis

systematic-debugging

/systematic-debugging

Use when something is broken — an error message, stack trace, failing test, crash, wrong output, "it doesn't work", build failure, or unexpected behavior. Finds the root cause with evidence before changing code, then saves the fix to memory.

Repository
soulkeeper ↗
Licence
MIT
Last repository change
26.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 26.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 when something is broken — an error message, stack trace, failing test, crash, wrong output, "it doesn't work", build failure, or unexpected behavior. Finds the root cause with evidence before changing code, then saves the fix to memory.

Triggers from the description

it doesn
Original author description

Use when something is broken — an error message, stack trace, failing test, crash, wrong output, "it doesn't work", build failure, or unexpected behavior. Finds the root cause with evidence before changing code, then saves the fix to memory.

How it works

  1. 1. Check memory first
  2. 2. Reproduce
  3. 3. Locate
  4. 4. Find the root cause
  5. 5. Fix
  6. 6. Prove it
  7. 7. Save the lesson
  8. When stuck
Original SKILL.md headings · 44 lines, 328 words
SKILL.md preview
---
name: systematic-debugging
description: Use when something is broken — an error message, stack trace, failing test, crash, wrong output, "it doesn't work", build failure, or unexpected behavior. Finds the root cause with evidence before changing code, then saves the fix to memory.
---

# Systematic Debugging

Do not guess-and-patch. Find the cause with evidence, fix it once, prove it is fixed.

## 1. Check memory first
`mem_search` with the error message, module name, or symptom. This bug (or a related issue) may already be solved.

## 2. Reproduce
- Get the exact error: full message, stack trace, command, input, environment.
- Reproduce it yourself with the smallest possible command or test. If you cannot reproduce it, state so and collect more information instead of guessing.
- When possible, write a failing test that captures the bug.

## 3. Locate
- Read the stack trace from the top frame **in project code**, not library internals.
- Read the real code at that location. Do not reason about code you have not inspected.
- Narrow down: add a temporary log/assertion, use `git log -p` / `git bisect` for regressions, or isolate components until the failure moves.

## 4. Find the root cause
Write one sentence: **"It fails because ___."** It must be backed by observed evidence (a printed value, a log line, a reproduced condition) — not a hunch.
Ask "why?" until you reach the root cause, not merely a symptom.

## 5. Fix
- Fix the cause with the smallest, most surgical change that does it.
- Do not silence the error (empty `catch`, `|| true`, `// @ts-ignore`, skipping tests) unless that *is* the correct fix and you explain why.
- Remove temporary debug logs.

## 6. Prove it
- The reproduction from step 2 now passes.
- Related tests and builds still pass (see `verify-before-done`).

## 7. Save the lesson
Save to memory using `mem_save`:
```
Title: <short bug name>
What: <symptom>
Why: <root cause>
Where: <file:line / module>
Lesson: <how to avoid or spot it next time>
```

## When stuck
After two failed hypotheses, stop and summarize: what you tried, what you observed, what you now suspect. Ask the user for the missing piece rather than trying random changes.

Versions

RepositoryScoreLicence
This page · fvkmizel/soulkeeper100MIT
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 9582417af064 (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
    A systematic method for finding the root cause of a bug, crash, error, or wrong output — reproduce, isolate, hypothesize, test, fix. Use when users report something broken, an exception/stack trace, flaky behavior, or 'why doesn't this work'. Triggers on mentions of bug, error,…
  • 100debug-detective
    Find the root cause of a bug, crash, error message or failing test, then fix it. Use when the user says "this is broken", "why does this fail", "I get this error", "the test is failing", "it worked yesterday", or pastes a stack trace.
  • 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.
  • 100debugging
    Systematic root-cause debugging methodology for any bug, test failure, crash, or unexpected behavior, in any language or framework. Use this before proposing a fix whenever something is broken — a failing test, a stack trace, a wrong output, an intermittent/flaky failure, or 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.
  • 100debug-issue
    Systematic debugging workflow for any code error, crash, test failure, or unexpected behavior. Use this skill whenever a user mentions an error, bug, exception, crash, test failure, or says something "isn't working", "is broken", "keeps failing", or "isn't behaving as expected"…

Feedback and reports

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