Skip to main content
skill CX Codex

debug · rsmdt — Claude Code skill: what it does, how to install

debug diagnoses software failures using a scientific method, strict hypothesis tracking, and root cause verification.

MIT ★ 587 updated 2026-10-26

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add rsmdt/the-startup
/plugin install start@the-startup
Open on GitHub

What debug does

This skill guides Claude Code through structured root cause analysis. Investigation begins at Phase 0: you must either trigger the issue on demand or add targeted telemetry. Speculating on a single unverified crash log is prohibited.

Findings use explicit status prefixes such as [hypothesis], [ruled out], and [demonstrated]. The investigation runs under three operational modes: conversational Standard mode, an adversarial Agent Team mode, or Dynamic Workflow for parallel testing. A fix is never applied without user confirmation and test verification.

What it helps with

  • reproduce intermittent errors through telemetry probes and invariant assertions
  • track competing failure theories without dropping unverified assumptions
  • trace entire execution paths from entry point to failure site
  • isolate demonstrable root causes before editing project files

Example prompts for the agent

  • /debug TypeError: Cannot read properties of undefined (reading 'id') at orderService.ts:42
  • /debug The checkout endpoint returns 500 only on rapid duplicate clicks
  • /debug Worker process hangs when consuming messages after Redis restarts

How to install debug

1Plugin marketplace

/plugin marketplace add rsmdt/the-startup
/plugin install start@the-startup

This installs the whole start plugin with all its skills

2Skills CLI (Vercel)

npx skills add rsmdt/the-startup --skill debug -a claude-code

3Manually: put the files in place

~/.claude/skills/debug/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/debug/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about debug

How to install debug in Claude Code?

Run two commands inside Claude Code: register the marketplace with /plugin marketplace add rsmdt/the-startup, then install the bundle via /plugin install start@the-startup.

What does the debug skill do?

It orchestrates conversational troubleshooting following an observe-hypothesize-experiment loop. It forces reproducible evidence before tagging an underlying defect as solved.

When does it require Agent Team or Dynamic Workflow mode?

Multi-investigator modes become mandatory when at least three hypotheses remain open, reproduction requires instrumentation, or the failure crosses two or more application layers.

Source text

SKILL.md · MIT
---
name: debug
description: Systematically diagnose and resolve bugs through conversational investigation and root cause analysis
user-invocable: true
argument-hint: "describe the bug, error message, or unexpected behavior"
---

## Persona

Act as an expert debugging partner through natural conversation. Follow the scientific method: observe, hypothesize, experiment, eliminate, verify.

**Bug Description**: $ARGUMENTS

## Interface

Investigation {
  perspective: ErrorTrace | CodePath | Dependencies | State | Environment
  location: string       // file:line
  checked: string        // what was verified
  found?: string         // evidence discovered (or clear if nothing found)
  hypothesis: string     // what this suggests
}

State {
  bug = $ARGUMENTS
  reproduction: Reliable | Once | Unknown
  hypotheses = []        // each tagged: pending | supported | ruled out | demonstrated
  evidence = []
  rootCause?: string     // only set when [demonstrated]
  mode: Standard | Agent Team | Dynamic Workflow
}

## Constraints

**Always:**
- Report findings with explicit epistemic prefixes — `[hypothesis]`, `[evidence: X]`, `[ruled out: X because Y]`, `[demonstrated]`. The prefix tells the reader (and you) the grade of the claim. See reference/hypothesis-hygiene.md.
- Treat reproducibility as a prerequisite for investigation. A hypothesis formed against a single observation is uncalibrated — there is no second data point to falsify against. See Phase 0.
- When stuck or uncertain, descend the investigation ladder before generating more hypotheses. Two untested hypotheses is the signal to instrument, not theorize. See reference/investigation-ladder.md.
- On user pushback: evaluate substance. If they named evidence or reasoning you didn't address, acknowledge specifically and reformulate. Otherwise, defend the position with reasoning. See reference/hypothesis-hygiene.md.
- Apply minimal fix, run tests, and report actual results.

**Never:**
- Pivot from hypothesis A to B without explicitly falsifying A or marking it `unresolved — deferred for reason`. Silently abandoning one hypothesis to look agreeable while moving to another is speculation laundering.
- Declare a fitting hypothesis a root cause. A root cause is `[demonstrated]` — toggling the suspected condition makes the bug appear or disappear on demand. Anything else is speculation in formal dress.
- Declare a bug "transient", "intermittent", or "fixed" without evidence. "It didn't recur in N attempts" is not evidence — it's insufficient instrumentation.
- Claim to have analyzed code you haven't read end-to-end. Skimming and forming three hypotheses is the failure mode the investigation ladder exists to catch.
- Apply fixes without user approval.
- Skip test verification after applying a fix.

## Reference Materials

- reference/perspectives.md — investigation perspectives, bug type patterns, perspective selection
- reference/investigation-ladder.md — software-level escalation when reading the code at the error site isn't enough
- reference/hypothesis-hygiene.md — vocabulary, ledger discipline, pushback handling
- reference/output-format.md — conversational guidelines per phase
- examples/output-example.md — concrete example: simple, source-readable bug
- examples/hard-bug-example.md — concrete example: bug requiring instrumentation and discipline

## Workflow

### 0. Reproduce

Before forming any hypothesis: can you trigger the bug on demand?

- **Yes** — note the trigger (inputs, environment, sequence of operations). Proceed to Understand.
- **No** — saw it once and the retry succeeded; or working from a logged error that isn't recurring. STOP. Hypothesizing on a single observation has no second data point to falsify against, and you will quietly accumulate plausible-sounding guesses with no way to choose between them.

  Either:
  - Find the trigger by varying inputs, timing, environment, or sequence until you can produce it on demand.
  - If the trigger remains elusive: instrument so the next recurrence is diagnosable. In order of cost: a failing test that captures the symptom from logs/inputs; probe logging at boundaries in the suspected path; assertions where invariants should hold.

Acceptable Phase 0 exits:
- "I reproduce reliably by doing X."
- "I cannot yet reproduce. Instrumentation is in place at A, B, C — the next occurrence will be diagnosable, and I'll resume from Phase 1 then."

Don't proceed past Phase 0 without one of these. Speculating on one-shot symptoms is the failure mode this phase exists to prevent.

### 1. Understand

Check git status, look for obvious errors, and read the relevant code path **end-to-end** — entry point, through every layer it traverses, to the failure site. Sampling code instead of tracing the path is a common skim-and-guess pattern; resist it. Most bugs labelled "mysterious" are visible in code that wasn't read.

Gather observations from error messages, stack traces, logs, and recent changes. Formulate initial hypotheses, each with an evidence prefix (typically `[hypothesis]` until tested).

Present brief summary per reference/output-format.md.

### 2. Select Mode

Ask the user to choose:
  Standard (default for simple bugs) — conversational step-by-step debugging
  Agent Team — adversarial investigation with competing hypotheses
  Dynamic Workflow — one inline workflow script tests each hypothesis in parallel, cross-checks them adversarially, and returns a ranked hypothesis ledger

**Agent Team or Dynamic Workflow is REQUIRED, not advisory, when ANY of:**
- ≥ 3 hypotheses still alive
- Bug is not reliably reproducible (Phase 0 exited via instrumentation rather than a trigger)
- Evidence from different perspectives contradicts
- A prior debugging attempt has been made and failed
- The failing path crosses ≥ 2 components or layers (service ↔ service, UI ↔ worker, etc.)

Standard mode is appropriate when a stack trace points at a clear file:line and one read of that file plausibly reveals the cause.

Prefer Dynamic Workflow over Agent Team when the hypotheses can each be tested independently; prefer Agent Team when investigators must react to each other's evidence as it arrives.

### 3. Investigate

match (mode) {
  Standard => {
    present theories conversationally, let user guide direction
    track every hypothesis on the task list using the ledger from reference/hypothesis-hygiene.md
    descend reference/investigation-ladder.md when reading code isn't enough
    narrow down through targeted investigation; close hypotheses explicitly before moving on
  }
  Agent Team => {
    spawn investigators per relevant perspectives (reference/perspectives.md)
    adversarial protocol: investigators challenge each other's hypotheses
    every claim carries the same vocabulary prefix
    strongest surviving hypothesis = candidate to be promoted to [demonstrated]
  }
  Dynamic Workflow => {
    run one dynamic workflow: one investigator per live hypothesis in parallel, each gathering evidence from its perspective (reference/perspectives.md)
    then an adversarial cross-check where each surviving hypothesis is challenged against the others' evidence
    every claim carries the same vocabulary prefix
    the workflow returns a ranked hypothesis ledger and applies no fix — present it to the user before continuing
  }
}

For Dynamic Workflow, these instructions are the opt-in: call the Workflow tool directly with an inline script. Do not load the workflow-authoring reference or assemble the script through shell commands first — runs that detour through either stall before launching. Choose `model` and `effort` per stage from what the stage does. Mechanical stages — running a command, gathering or quoting sources, mapping text into a fixed schema — can run on a smaller, faster model at lower effort. Analysis, writing, and judging another agent's work need the strongest model. A judging stage never runs on a weaker model than the stage it judges. When unsure, omit `model` so the stage inherits the session model.

### 4. Find Root Cause

Process evidence:
1. Correlate across perspectives.
2. Rank hypotheses by supporting evidence — refer to the ledger in reference/hypothesis-hygiene.md.
3. The candidate root cause must be `[demonstrated]` — you can switch the bug on and off by toggling a condition. If the strongest candidate remains `[hypothesis]` or `[supported]`, descend the investigation ladder; do not promote it.
4. Present root cause with the toggling experiment that demonstrated it, and file:line where applicable.

### 5. Fix and Verify

Propose minimal fix targeting root cause.
Ask the user to choose: Apply fix | Modify approach | Skip

Apply change, run tests, report actual results honestly.

Ask the user to choose: Add test case for this bug | Check for pattern elsewhere | Done

© Rudolf S. · MIT · rsmdt/the-startup

Similar skills

All skills for Testing and QA →

debug by other authors comes first.

debug official anthropics debug is a Claude Code skill that reproduces errors, traces their causes, and proposes fixes. It starts from an error message, stack trace, or unexpected behavior. CX Codex +1 6,100installs debug jsmastery-pro debug runs a structured investigation loop to find a bug's root cause, applies the minimal fix, and prepares a regression test. CX Codex +1 5,100installs debug Yeachan-Heo debug diagnoses broken OMC sessions, workflow failures, and repo state issues using traces and targeted reproduction. CX Codex +1 705installs debug cyrusagents debug works through a reported bug from reproduction to a minimal fix. Use it when you need to trace an error and verify the result. CX Codex +1 871installs debug parcadei debug is a Claude Code skill that investigates issues through logs, database state, and Git history. It starts during manual testing or implementation when something goes wrong. CX Codex +1 511installs debug-like-expert Lex Christopherson debug-like-expert activates a structured debugging protocol for complex issues when standard troubleshooting fails. Gathers evidence, tests hypotheses, and finds root causes instead of applying quick fixes. CX Codex +1 ★ 1,988repo stars principle-attack-the-premise backnotprop principle-attack-the-premise is a Claude Code skill that tests a shared premise after two or more fixes fail at the same gate. It checks the assumption before another fix is written. CX Codex +1 10,100installs debug-mantra thananon debug-mantra is a Claude Code skill that guides debugging through reproduction, failure tracing, hypothesis testing, and experiment review. It activates with /debug-mantra or when a debugging request or error log appears. CX Codex +1 5,100installs debugging mrgoonie Enforces a disciplined debugging methodology that stops guesswork and requires fresh test proof before marking tasks done. CX Codex +1 580installs debugger VoltAgent Community debugger diagnoses software failures, reads stack traces, and isolates root causes to fix elusive bugs. Helpful when logs alone do not explain a crash. CX Codex 13,459installs w-debug blockmatic-icebox The w-debug Claude Code skill traces failures through logs and reproduction steps. After an authorized fix, it reruns the original scenario and affected checks. CX Codex +1 647installs

From the same set50

The whole set →
design-system design-system designs a service's architecture — pattern, data stores, scaling path — and hands back diagrams and ADRs. Useful when you're deciding whether to split a monolith. CX Codex ★ 587repo stars optimize-performance optimize-performance — a performance optimization subagent for Claude Code. Targets slow page loads, backend API latency, database queries, and memory leaks based on profiling metrics. CX Codex ★ 587repo stars archive Turns a finished specification into a compact file in .start/archive/ and removes its working folder. Run it after implementation to clear completed work from .start/specs/. CX Codex +1 ★ 587repo stars implement An implementation orchestrator that reads slice and scenario tasks from the spec tracker, then launches a workflow which builds each slice and retries code→eval until holdout scenarios pass. CX Codex +1 ★ 587repo stars the-meta-agent The the-meta-agent subagent designs, audits, and refactors Claude Code subagents. Use it when an agent needs a focused scope, a clear workflow, or a specification check. CX Codex ★ 587repo stars improve improve finds modules with bloated interfaces and proposes refactors that turn them into deep ones — testable and easy for an agent to navigate. CX Codex +1 ★ 587repo stars specify-solution The specify-solution skill for Claude Code drafts and validates technical solution designs in spec.md based on product requirements. CX Codex +1 ★ 587repo stars specify-plan The specify-plan skill turns requirements and solution design into a phased plan and tracker tasks for /implement. Use it when a specification is ready to break into testable slices. CX Codex +1 ★ 587repo stars

Project sponsors

Companies that keep this analytics open