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.
- Author
- miaoge-ge ↗
- Repository
- coding-agent-skills ↗
- Licence
- MIT
- Last repository change
- 31.05.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 31.05.2026, without references to retired models or APIs.
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
- When to Use
- When NOT to Use
- The Method
- Tactics by symptom
- Common Mistakes
- Examples
- See Also
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
| Repository | Score | Licence |
|---|---|---|
| This page · miaoge-ge/coding-agent-skills | 100 | MIT |
| traylinx/switchAILocal | 90 | Apache-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…