# debug

debug is a Claude Code skill that enforces hypothesis-driven debugging. It stops the agent from editing files until the root cause is framed, tested, and confirmed.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 88 repo stars
- Author: alexj11324
- License: AGPL-3.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/alexj11324/Mikka/tree/HEAD/.claude/skills/debug/SKILL.md
- Updated: 2026-11-17
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/alexj11324-debug

## What it does

This skill forces the assistant into a structured investigation routine instead of making random edits. The agent starts by recording expected versus actual behavior, identifying recent codebase changes, and checking reproducibility. It then drafts a falsifiable hypothesis and narrows scope using `git bisect`, bottom-up stack trace inspection, or minimal reproduction cases.

Code modifications are blocked until the failure is deliberately reproduced through a targeted assertion or log. Fixes must remain minimal and target the underlying cause rather than treating symptoms. Every resolved issue requires an accompanying regression test to prevent recurring defects.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add alexj11324/Mikka --skill debug -a claude-code
```

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

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add alexj11324/Mikka --skill debug -a codex
```

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

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add alexj11324/Mikka --skill debug -a cursor
```

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

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install alexj11324/Mikka .claude/skills/debug
```

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

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add alexj11324/Mikka --skill debug -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/alexj11324/Mikka --path .claude/skills/debug
```

### Windsurf (Devin Desktop)

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

### 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/alexj11324/Mikka/tree/HEAD/.claude/skills/debug/SKILL.md

## When to use it
- trace failures to their root cause without guesswork
- isolate breaking commits using `git bisect`
- write regression tests that verify the fix
- analyze bottom-up stack traces in application code

## Example prompts
- "I am getting an unexpected TypeError in this module, investigate why"
- "The test suite is failing after the latest merge, locate the cause"
- "The checkout calculates the wrong total on discounted carts, find the bug"

## Similar
- [ce-debug](https://affpapa.org/en/nevibecode/skills/ce-debug.md) — skill · 3700 installs
- [debug-like-expert](https://affpapa.org/en/nevibecode/skills/debug-like-expert.md) — skill · ★ 1988 repo stars
- [debug-systematic](https://affpapa.org/en/nevibecode/skills/debug-systematic.md) — skill · 152 installs
- [principle-attack-the-premise](https://affpapa.org/en/nevibecode/skills/principle-attack-the-premise.md) — skill · 10100 installs
- [systematic-debugging](https://affpapa.org/en/nevibecode/skills/spencerpauly-systematic-debugging.md) — skill · 604 installs
- [gjalla-debug](https://affpapa.org/en/nevibecode/skills/gjalla-debug.md) — skill · 357 installs

## Other versions with the same name
- [debug · anthropics](https://affpapa.org/en/nevibecode/skills/debug.md) — 6100 installs
- [debug · jsmastery-pro](https://affpapa.org/en/nevibecode/skills/jsmastery-pro-debug.md) — 5100 installs
- [debug · yeachan-heo](https://affpapa.org/en/nevibecode/skills/yeachan-heo-debug.md) — 705 installs
- [debug · cyrusagents](https://affpapa.org/en/nevibecode/skills/cyrusagents-debug.md) — 871 installs
- [debug · parcadei](https://affpapa.org/en/nevibecode/skills/parcadei-debug.md) — 511 installs

From the same set: [alexj11324/mikka](https://affpapa.org/en/nevibecode/by/alexj11324/mikka.md) — 47 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
