# Debug Code Systematically

> Debug code with a scientific method instead of guessing. Use when fixing bugs, regressions, crashes, stack traces, failing tests, unexpected behavior, or "not working" reports. Produces a reproduced failure, tested hypotheses, isolated root cause, fix, and regression check.

- **Type:** Skill
- **Install:** `agentstack add skill-ariaxhan-the-agent-library-debug-code-systematically`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ariaxhan](https://agentstack.voostack.com/s/ariaxhan)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ariaxhan](https://github.com/ariaxhan)
- **Source:** https://github.com/ariaxhan/the-agent-library/tree/main/code-engineering/debug-code-systematically

## Install

```sh
agentstack add skill-ariaxhan-the-agent-library-debug-code-systematically
```

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

## About

# Debug Code Systematically

Debugging is theory work. Reproduce, hypothesize, isolate, fix root cause, and prove the original failure is gone.

## 1. Reproduce

Capture:

- Exact input or action
- Expected behavior
- Actual behavior
- Error output or stack trace
- Environment
- Frequency

If reproduction is not possible, add targeted logging or a minimal observation plan before changing code.

## 2. List hypotheses

Write at least three plausible causes before pursuing one. Read all error output first.

For each hypothesis, name what evidence would disprove it. Do not chase the first explanation that feels right.

## 3. Isolate

Use binary search:

- Call chain: inspect the midpoint, then recurse into the failing half
- Git history: bisect between known-good and known-bad
- Input: cut the failing input until the minimal case remains
- Boundaries: log inputs/outputs at module or service edges

Stop exploring when the failure is localized to a specific function, commit, input shape, or external dependency.

## 4. Find root cause

State the violated invariant in one sentence.

Do not patch only the visible failure site unless that is the actual defect. A null check at a crash site is usually not enough; ask why null arrived there.

## 5. Fix with a regression check

Make the smallest root-cause fix. Add or update a test/check that fails before the fix and passes after.

Run:

- The original failing case
- The regression check
- Nearby edge cases
- The nearest relevant test suite

## 6. Report evidence

Return:

- Reproduction
- Root cause
- Files changed
- Regression check
- Commands run and results
- Any residual risk

If you could not reproduce or fully verify, say that directly.

## Source & license

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

- **Author:** [ariaxhan](https://github.com/ariaxhan)
- **Source:** [ariaxhan/the-agent-library](https://github.com/ariaxhan/the-agent-library)
- **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-ariaxhan-the-agent-library-debug-code-systematically
- Seller: https://agentstack.voostack.com/s/ariaxhan
- 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%.