# cognitive-debugger

cognitive-debugger — a diagnostic subagent for Claude Code that investigates reasoning breakdowns, traces error propagation across logic chains, and applies WFGY recovery protocols.

- subagent · `type=agent` · Claude Code, Codex, Cursor · ★ 1357 repo stars
- Author: qdhenry
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/qdhenry/Claude-Command-Suite/tree/HEAD/.claude/agents/wfgy/cognitive-debugger.md
- Updated: 2026-03-01
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/agents/cognitive-debugger

## What it does

This subagent acts as an investigator for broken model reasoning. It spots circular logic, invalid inferences, and context drift, mapping out how an initial mistake cascaded through subsequent arguments.

Under the hood, it operates via internal commands prefixed with an asterisk, such as `*diagnose-failure`, `*trace-error`, `*rollback`, and `*step-debug`. Tracing depth reaches 10 nodes, with up to 5 rollback checkpoints and 20 breakpoints. Failures trigger light, moderate, or severe recovery paths based on a calculated resonance threshold.

Advanced repair commands like `*apply-bbcr` expect dependency definitions inside `.claude/commands/wfgy/` and `.claude/commands/reasoning/`, so missing files in those paths will stall recovery steps.

## Install

### Claude Code (native platform)

**Manually: put the files in place**
- File: `.claude/agents/cognitive-debugger.md` — For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

### Codex

**Manually: put the files in place**
- File: `.codex/agents/cognitive-debugger.toml` — Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/

### Cursor

**Manually: put the files in place**
- File: `.cursor/agents/cognitive-debugger.md` — Cursor also reads .claude/agents/

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/qdhenry/Claude-Command-Suite/tree/HEAD/.claude/agents/wfgy/cognitive-debugger.md

## When to use it
- pinpoint the root cause of an invalid deduction
- track how a false premise traveled across steps
- roll back the reasoning chain to the last good checkpoint
- reconstruct damaged conclusions using BBCR correction

## Example prompts
- Run `*diagnose-failure` on the previous answer to locate the invalid step
- Use `*trace-error` to map where the premise collapsed
- Execute `*step-debug` to inspect the reasoning chain node by node

## Similar
- [cognitive-pattern](https://affpapa.org/en/nevibecode/skills/cognitive-pattern.md) — skill · 757 installs
- [llm-debugger](https://affpapa.org/en/nevibecode/skills/llm-debugger.md) — skill · 259 installs
- [adk-debugger](https://affpapa.org/en/nevibecode/skills/adk-debugger.md) — skill · 1700 installs
- [debugger](https://affpapa.org/en/nevibecode/skills/zhaono1-debugger.md) — skill · 756 installs
- [node-inspect-debugger](https://affpapa.org/en/nevibecode/skills/node-inspect-debugger.md) — skill · 403 installs
- [magento-issue-debugger](https://affpapa.org/en/nevibecode/skills/magento-issue-debugger.md) — skill · 274 installs

From the same set: [qdhenry/claude-command-suite](https://affpapa.org/en/nevibecode/by/qdhenry/claude-command-suite.md) — 112 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
