# debug

The debug rule sets the order for troubleshooting: gather evidence and context, explain the cause, then edit code. It applies when an error persists or a fix is incomplete.

- rule · `type=rule` · Claude Code, Cline, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop) · ★ 1054 repo stars
- Author: Bhartendu-Kumar
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Bhartendu-Kumar/rules_template/tree/HEAD/.cursor/rules/debug.mdc
- Updated: 2025-07-17
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/rules/debug

## What it does

The rule covers errors that did not go away on the first pass and fixes that came out incomplete. Otherwise it stays out of the way; its own description limits it to the moment the agent is stuck.

Work begins with evidence. Error messages, logs and the visible symptoms get collected, plus context pulled from project files, while architecture and the current task come from `@memory.mdc`. The agent then says what it observed and why that points at this cause rather than a neighbouring one. Short on facts, it gathers more and may ask you to clarify.

Editing comes last. The routine calls for `<ANALYZE CODE>` over the affected area, a search for similar cases already solved in `@error-documentation.mdc`, then the fix through `<SYSTEMATIC CODE PROTOCOL>` and `<TESTING>`. Those blocks sit in `implement.mdc` from the same repo, so a project without that file leaves part of the routine without its steps.

## Install

### Cursor (native platform)

**Manually: put the files in place**
- File: `.cursor/rules/debug.mdc` — Frontmatter: description, globs, alwaysApply

### Claude Code

**Manually: put the files in place**
- File: `.claude/rules/debug.md` — The paths frontmatter field limits the files: move globs from the source into paths

### Codex

**AGENTS.md**
- Codex reads AGENTS.md: paste the rule text there

### GitHub Copilot

**Manually: put the files in place**
- File: `.github/instructions/debug.instructions.md` — The applyTo field sets which files it applies to: move globs from the source into applyTo

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/rules/debug.md`

### Cline

**Manually: put the files in place**
- File: `.clinerules/debug.md`

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/Bhartendu-Kumar/rules_template/tree/HEAD/.cursor/rules/debug.mdc

## When to use it
- untangle a test that keeps failing instead of patching blindly
- collect logs, symptoms and file context before touching code
- tell an architecture misalignment from an ordinary bug
- reuse a similar fix already recorded in the project
- show the reasoning before the agent edits anything

## Example prompts
- The build keeps failing in `cart_test.py`; run the debug routine and gather observations first.
- Don't patch yet. Walk through the cause step by step and present your reasoning.
- Check `@error-documentation.mdc` for a similar issue before you propose a fix.

## Similar
- [debug-my-harness](https://affpapa.org/en/nevibecode/skills/debug-my-harness.md) — skill · 1500 installs
- [debug-issue](https://affpapa.org/en/nevibecode/skills/debug-issue.md) — skill · 1100 installs
- [gjalla-debug](https://affpapa.org/en/nevibecode/skills/gjalla-debug.md) — skill · 357 installs
- [vue-debug-guides](https://affpapa.org/en/nevibecode/skills/vue-debug-guides.md) — skill · 28400 installs
- [no-workarounds](https://affpapa.org/en/nevibecode/skills/no-workarounds.md) — skill · 593 installs
- [debug-mantra](https://affpapa.org/en/nevibecode/skills/debug-mantra.md) — skill · 5100 installs

From the same set: [bhartendu-kumar/rules_template](https://affpapa.org/en/nevibecode/by/bhartendu-kumar/rules_template.md) — 11 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
