# debugging

A skill that walks the agent through a reproduce → isolate → verify loop for concrete bugs, regressions and flaky failures. Useful once you already have a failing test or request.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 361 installs · ★ 50
- Author: akillness
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/akillness/jeo-skills/tree/HEAD/.agent-skills/debugging/SKILL.md
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/skills/akillness-debugging

## What it does

The skill gives the agent an eight-step frame. It starts by freezing the failure definition: expected behavior, actual behavior, trigger, environment, and how confident you are. Then it picks the cheapest evidence source — rerun the failing command, compare recent changes for a regression, repeat runs for a flaky test, diff configs when the failure only shows up in CI or staging.

From there the agent builds the smallest reproducer and narrows the boundary: UI versus API, database, worker, config, dependency. One check per hypothesis, not five patches at once. Three references ship with it: `references/debug-loop.md` for the full experiment scaffold, `references/mode-selection-and-fast-checks.md` with packets for regressions, flakes, env mismatches and artifact-led cases, and `references/handoff-boundaries.md` so work that belongs elsewhere stays elsewhere.

Tool access is limited to `Read`, `Grep`, `Glob`, `Bash` and `Write`. The skill does not take raw logs without a narrowed symptom, test-policy design, PR review or performance tuning — it hands those off. When reproduction or isolation still fails, the agent is told to state low confidence and ask for one missing artifact instead of guessing at a root cause.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add akillness/jeo-skills --skill debugging -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/debugging/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/debugging/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add akillness/jeo-skills --skill debugging -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/debugging/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add akillness/jeo-skills --skill debugging -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/debugging/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install akillness/jeo-skills debugging
```

2. **Manually: put the files in place**
- File: `.github/skills/debugging/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add akillness/jeo-skills --skill debugging -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/akillness/jeo-skills --path .agent-skills/debugging
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/debugging/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add akillness/jeo-skills --skill debugging -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/akillness/jeo-skills/tree/HEAD/.agent-skills/debugging/SKILL.md

## When to use it
- reproduce a failing test in isolation
- narrow a failure to one module or config branch
- find the commit that introduced a regression
- gather repeated-run evidence for a flaky test
- compare local behavior against CI

## Example prompts
- Reproduce the failure in `test_checkout.py` and narrow it to one module
- This is a regression — find the change window and try `git bisect`
- The test fails intermittently; measure the rate with repeated runs and isolate one case

## Similar
- [systematic-debugging](https://affpapa.org/en/nevibecode/skills/spencerpauly-systematic-debugging.md) — skill · 545 installs
- [debugging-wizard](https://affpapa.org/en/nevibecode/skills/debugging-wizard.md) — skill · 5100 installs
- [bug-reproduction](https://affpapa.org/en/nevibecode/skills/bug-reproduction.md) — skill · 1400 installs
- [debugging-and-error-recovery](https://affpapa.org/en/nevibecode/skills/debugging-and-error-recovery.md) — skill · 62800 installs
- [hunt](https://affpapa.org/en/nevibecode/skills/hunt.md) — skill · 14900 installs
- [test-reliability](https://affpapa.org/en/nevibecode/skills/test-reliability.md) — skill · 1100 installs

## Other versions with the same name
- [debugging · tursodatabase](https://affpapa.org/en/nevibecode/skills/debugging.md) — 1300 installs
- [debugging · mrgoonie](https://affpapa.org/en/nevibecode/skills/mrgoonie-debugging.md) — 569 installs

From the same set: [akillness/jeo-skills](https://affpapa.org/en/nevibecode/by/akillness/jeo-skills.md) — 22 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md