# Systematic Debugging

> Root-cause a bug with a hypothesis-driven loop instead of shotgun edits. Use when a bug isn't obvious after the first look, or when asked to "find out why" something fails.

- **Type:** Skill
- **Install:** `agentstack add skill-jnmetacode-skillet-systematic-debugging`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jnMetaCode](https://agentstack.voostack.com/s/jnmetacode)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jnMetaCode](https://github.com/jnMetaCode)
- **Source:** https://github.com/jnMetaCode/skillet/tree/main/skills/systematic-debugging
- **Website:** https://github.com/jnMetaCode/local-agent-toolkit

## Install

```sh
agentstack add skill-jnmetacode-skillet-systematic-debugging
```

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

## About

# systematic-debugging

Never fix what you can't reproduce; never explain what you haven't observed.
The loop is: **reproduce → observe → hypothesize → test the hypothesis →
narrow**. One variable at a time.

## Procedure

1. **Reproduce first.** Find the smallest, fastest command that shows the
   failure deterministically. If it's flaky, make the loop tight
   (`while ./repro; do :; done`) and treat flakiness itself as a clue
   (timing, ordering, shared state).
2. **Read the actual error.** The full message, the *first* stack frame in
   your own code, and the line right before things went wrong. Resist
   pattern-matching to a familiar failure — verify this one.
3. **State a falsifiable hypothesis** ("the cache returns stale entries after
   a restart") and pick the *cheapest* observation that could kill it: a log
   line, an assertion, a debugger breakpoint, one curl.
4. **Bisect the space**, whichever axis is cheapest:
   - history: `git bisect run ./repro`
   - data: half the failing input, recurse
   - stack: confirm the bad value at the boundary between two layers, then
     descend into the guilty one only
5. **The fix must explain the symptom.** Before writing it, say *why* this
   cause produces *exactly* this behavior. If the explanation is fuzzy, you've
   found *a* bug, maybe not *the* bug.
6. **Prove it**: the repro from step 1 now passes, AND a new regression test
   fails without the fix. Then look for siblings — the same mistake usually
   exists elsewhere (`grep` for the pattern you just fixed).

## Anti-patterns

- Changing two things between observations — you learn nothing from the result.
- "It works now" without knowing why it failed — it will be back.
- Adding sleeps to fix timing issues — that's hiding the race, not fixing it.
- Debugging through the framework before confirming your own code's inputs
  and outputs at the boundary.

## Source & license

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

- **Author:** [jnMetaCode](https://github.com/jnMetaCode)
- **Source:** [jnMetaCode/skillet](https://github.com/jnMetaCode/skillet)
- **License:** MIT
- **Homepage:** https://github.com/jnMetaCode/local-agent-toolkit

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:** yes
- **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-jnmetacode-skillet-systematic-debugging
- Seller: https://agentstack.voostack.com/s/jnmetacode
- 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%.