# gjalla-debug

gjalla-debug — a skill that guides agents to find the root cause of a bug with evidence before proposing a fix. Works with Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 357 installs · ★ 3 repo stars
- Author: gjalla
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/gjalla/engineering/tree/HEAD/skills/gjalla-debug/SKILL.md
- Updated: 2026-09-20
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/gjalla-debug

## What it does

gjalla-debug trains the agent to run an investigation: record the exact symptom, reproduce the problem or state why it could not be reproduced, confirm the code is current, pull context from repo rules and change history, locate the root instead of the first observable consequence. After diagnosis, the skill requires counting how many places in the codebase contain the same defect and writing a test that currently fails and will pass after the fix.

The output is a structured report: symptom, mechanism with file and line, why the broken state was reachable, blast radius (list of locations and count), confidence level (what was verified directly, what was inferred), proposed fix with test. If the fix touches system primitives, the skill stops and hands off to `gjalla-spec`.

The skill forbids forming a theory before gathering data. Without reproduction, it switches to logs, telemetry and database state but marks the diagnosis as less certain.

## Install

### Claude Code (native platform)

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

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

### Codex

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

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

### Cursor

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

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

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install gjalla/engineering skills/gjalla-debug
```

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

### Gemini CLI

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

2. **Platform CLI**
```bash
gemini skills install https://github.com/gjalla/engineering --path skills/gjalla-debug
```

### Windsurf (Devin Desktop)

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

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add gjalla/engineering --skill gjalla-debug -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/gjalla/engineering/tree/HEAD/skills/gjalla-debug/SKILL.md

## When to use it
- locate the root cause instead of the first visible consequence
- reproduce the issue or state why reproduction failed
- count how many locations in the repo contain the same defect
- write a test that currently fails and passes after the fix
- pull context from repo rules and change history

## Example prompts
- Diagnose why the second save in a session returns outdated data
- Reproduce the error from the ticket and explain the mechanism
- Count how many places we call this method without the guard that caused the bug

## Similar
- [08-debug](https://affpapa.org/en/nevibecode/skills/08-debug.md) — skill · ★ 571 repo stars
- [error-diagnostics-smart-debug](https://affpapa.org/en/nevibecode/skills/error-diagnostics-smart-debug.md) — skill · 1 install
- [debug-like-expert](https://affpapa.org/en/nevibecode/skills/debug-like-expert.md) — skill · ★ 1988 repo stars
- [debug-agent](https://affpapa.org/en/nevibecode/agents/debug-agent.md) — subagent · ★ 3951 repo stars
- [systematic-debugging](https://affpapa.org/en/nevibecode/skills/systematic-debugging.md) — skill · 306118 installs
- [agent-browser](https://affpapa.org/en/nevibecode/skills/vercel-labs-agent-browser.md) — skill · 1600000 installs
- [improve-codebase-architecture](https://affpapa.org/en/nevibecode/skills/improve-codebase-architecture.md) — skill · 1163035 installs
- [tdd](https://affpapa.org/en/nevibecode/skills/tdd.md) — skill · 1141062 installs

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