Skip to content
Skills Library
Programming · Analysis

debugging-expert

/debugging-expert

Expert systematic debugging and root-cause analysis. Trigger keywords: debug, bug, error, exception, crash, stack trace, reproduce, root cause, works on my machine, intermittent, heisenbug, regression, git bisect, race condition. Use to diagnose failures methodically, find the real cause, and stop guess-and-check fixing.

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

Expert systematic debugging and root-cause analysis. Trigger keywords: debug, bug, error, exception, crash, stack trace, reproduce, root cause, works on my machine, intermittent, heisenbug, regression, git bisect, race condition. Use to diagnose failures methodically, find the real cause, and stop guess-and-check fixing.

Original author description

Expert systematic debugging and root-cause analysis. Trigger keywords: debug, bug, error, exception, crash, stack trace, reproduce, root cause, works on my machine, intermittent, heisenbug, regression, git bisect, race condition. Use to diagnose failures methodically, find the real cause, and stop guess-and-check fixing.

How it works

  1. When to Use
  2. When NOT to Use
  3. The Method
  4. Tactics by symptom
  5. Common Mistakes
  6. Examples
  7. See Also
Original SKILL.md headings · 74 lines, 592 words
SKILL.md preview
---
name: debugging-expert
description: "Expert systematic debugging and root-cause analysis. Trigger keywords: debug, bug, error, exception, crash, stack trace, reproduce, root cause, works on my machine, intermittent, heisenbug, regression, git bisect, race condition. Use to diagnose failures methodically, find the real cause, and stop guess-and-check fixing."
---

# Debugging Expert

> Reproduce, then bisect. The bug is rarely where you think — follow evidence, change one variable at a time, and fix the cause (with a regression test), not the symptom.

## When to Use
- A bug, crash, exception, or wrong output to diagnose.
- Intermittent / "works on my machine" / heisenbug situations.
- Locating which change introduced a regression.
- Stuck guessing and editing code at random.

## When NOT to Use
- Writing the regression test after diagnosis → `testing-expert`.
- It's slow, not wrong → `performance-expert`.
- Refactoring without a defect → `refactoring-expert`.

## The Method

### 1. Reproduce reliably first
- Get a **minimal, deterministic reproduction** before changing anything — you can't confirm a fix for a bug you can't trigger. Pin inputs, environment, versions, and timing.
- For intermittent bugs, find what increases the rate (load, ordering, specific data, concurrency) and amplify it; add logging to capture the failing case.

### 2. Read the evidence
- Read the **entire** error and stack trace top to bottom — the root cause is often above the most obvious frame. Don't skim or assume.
- Check what changed: `git log`/`git diff` since it last worked, recent deploys, dependency bumps, config/env differences. Inspect logs around the failure timestamp.

### 3. Hypothesize → predict → test
- Form **one** hypothesis, predict exactly what you'd observe if it's true, then test that prediction. Confirm or eliminate before moving on.
- **Bisect** the search space: binary-search the code path, the input data, or history (`git bisect`). Add assertions/logging at the boundary between "still correct" and "already wrong" to bracket the defect.
- Question assumptions, including "this library/my framework can't be the problem." Verify, don't believe.

### 4. Fix the cause, prevent recurrence
- Explain **why** it happened before patching. Fix the root cause, not the visible symptom. Add a test that fails without the fix, then look for sibling bugs of the same class.

## Tactics by symptom
| Symptom | Tactic |
|---------|--------|
| Regression "used to work" | `git bisect` to the first bad commit |
| Intermittent/race | add logging/IDs, stress ordering, run with race detector |
| Wrong value somewhere | binary-search with assertions to bracket where state corrupts |
| "Works on my machine" | diff env/versions/config; reproduce in a clean container |
| Crash/exception | read full trace; reproduce the exact input |

## Common Mistakes
- **Changing multiple things at once** → you won't know what fixed (or broke) it.
- **Fixing the symptom** (swallow the exception, clamp the value) → bug resurfaces elsewhere.
- **Skimming the stack trace** → miss the real frame and root cause.
- **Debugging without a reproduction** → guessing; can't verify the fix.
- **Trusting assumptions** ("the input is valid", "the lib is fine") → verify each.
- **No regression test** after the fix → it comes back.
- **`print` shotgun everywhere** → use targeted, bracketing logging or a debugger/breakpoints.

## Examples

**Bisect a regression**
```bash
git bisect start
git bisect bad                 # current is broken
git bisect good v1.4.0         # known-good tag
# test each checkout, then mark good/bad; ~log2(N) steps -> first bad commit
git bisect reset
```

**Bracket where state goes wrong**
```python
assert invariant(state), f"invariant broke after step {i}: {state!r}"
# move the assert earlier/later to corner the corrupting step
```

## See Also
- `testing-expert` — lock the fix in with a failing-first regression test.
- `performance-expert` — same evidence-driven method, for "slow".
- `github-master` — `git bisect`, `reflog`, and history forensics.

Versions

RepositoryScoreLicence
This page · miaoge-ge/coding-agent-skills100MIT
traylinx/switchAILocal90Apache-2.0

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

  • 100debug
    Systematic root-cause debugging — reproduce, isolate, hypothesize, fix with TDD. Use when: bug, error, fix, broken, crash, exception, not working, unexpected behavior, regression.
  • 100systematic-debugging
    Finds the root cause of bugs with a disciplined reproduce, isolate, hypothesize, verify loop (including git bisect) instead of guess-and-patch, then locks the fix in with a regression test. Use when the user reports a bug, crash, failing test, flaky behavior, regression, or "it works on my machine".
  • 100systematic-debugging
    Root-cause-first debugging methodology for any bug, test failure, exception, or unexpected behavior — mandates investigation before proposing fixes. Use when something is broken, not working, crashing, or throwing errors; triggers: debug, error, bug, exception, stack trace, not working, crash.
  • 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
    Systematically root-causes software bugs using a reproduce → isolate → hypothesize → bisect → verify methodology, replacing guess-and-check debugging with a disciplined, evidence-driven investigation. Use this skill when a user reports a bug, a test is failing intermittently or…
  • 90investigate-root-cause
    Use when encountering ANY bug, error, test failure, or unexpected behavior. Activate for keywords like "bug", "error", "failing", "broken", "doesn't work", "unexpected", "crash", "exception", "TypeError", "undefined", stack traces, or any error message. Also trigger when tests…

Feedback and reports

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