# 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.

- **Type:** Skill
- **Install:** `agentstack add skill-miaoge-ge-coding-agent-skills-debugging-expert`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Miaoge-Ge](https://agentstack.voostack.com/s/miaoge-ge)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Miaoge-Ge](https://github.com/Miaoge-Ge)
- **Source:** https://github.com/Miaoge-Ge/coding-agent-skills/tree/main/plugins/debugging-expert/skills/debugging-expert

## Install

```sh
agentstack add skill-miaoge-ge-coding-agent-skills-debugging-expert
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Miaoge-Ge](https://github.com/Miaoge-Ge)
- **Source:** [Miaoge-Ge/coding-agent-skills](https://github.com/Miaoge-Ge/coding-agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-miaoge-ge-coding-agent-skills-debugging-expert
- Seller: https://agentstack.voostack.com/s/miaoge-ge
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.