diagnose · git:20261115.0326cb7 · 2026-11-15 · sha256 540dd76f0b3bc165

diagnose git:20261115.0326cb7A

Immutable. This exact content never changes and is served at /api/v1/blob/540dd76f0b3bc165.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_6ciwa6cyrjytbebd/540dd76f0b3bc16504dadd41d5dbf500f6ea89aae46f292b0ee724d5d4e8bcc8.json

Then /plugin install diagnose@markdownregistry-6ciwa6cyrjytbebd in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: diagnose
description: "Finds the proven cause of wrong behavior from a reproduction, then fixes it with a test seen red before green. Use when the user reports a bug, error, crash, regression or slowdown ('why does X fail', 'this broke', 'debug this'). Not for a missing feature or a failing pull request check."
argument-hint: <symptom, failing command or error>
model: opus
effort: medium
---
# Diagnose

Prove the cause before changing code, because a fix for a guessed cause hides the bug. Until then this skill comes before `exo:spec` and `exo:build`; in plan mode, write the plan in `exo:spec`'s format with the reproduction test as Task 1.

## Steps

1. **Reproduce.** Read an existing log or `.exo/` report, then find one command that shows the failure. Send long output to `<debug-dir>/repro.log`, where `node "${CLAUDE_PLUGIN_ROOT}/lib/scratch-path.mjs" debug` prints `<debug-dir>`, and read its `tail -n 40`. No repro: report the evidence and fix nothing. Ask the user only when the symptom itself is unclear.
   - It worked before: `node "${CLAUDE_SKILL_DIR}/scripts/bisect.mjs" --repro "<command>"` prints the first bad commit; its hunks are the first suspects.
   - Slowdown: time the reported path five times and record the median and spread first. A captured profile is fixed data: load it, do not re-run, and name the hot frame's file, symbol and line.
2. **Instrument.** Keep two hypotheses and observe once where they diverge.
3. **Isolate.** Remove inputs or branches until one more clears the symptom; two rounds with no change end it. Proven means a causal line plus a mechanism that predicts the symptom.
4. **Predict, then fix.** State the causal line and the output the fix changes, and change only that. Before you edit code yourself, read the code rules that the first bullet of `${CLAUDE_PLUGIN_ROOT}/agents/builder.md` names, because they bind your edit as they bind a builder's. Write a test that fails for the cause and quote its failure before the fix, its pass after. Never revert or stash to show red, because a test never seen red proves nothing. Ask the user before any destructive step. A slowdown fix stays only when the median improves by more than the spread.
5. **Prove.** Rerun the repro, the isolated case and the suite. A fix that must change a second module, beyond the one holding the cause, goes back to step 1.
6. **Review.** When the fix changed more than two files, added a dependency, or crosses a public signature, persisted format or security boundary, run `code-review` at level `low` and fix its findings under step 5.

## Delegating

When reading alone does not prove the cause, send a fresh `exo:builder` `investigator-prompt.md` (Steps 1 to 3). Once its handoff says `Status: proven`, ask where the fix commits unless the request or caller already says, then send a fresh `exo:builder` `fixer-prompt.md` (Steps 4 and 5); resume a `failed` one once with SendMessage. Commit the new test alone, then the fix. Read only their status lines and handoff fields.

## Report

Invoked by another stage: return without asking. Else state the cause in plain words, whether the fix is proven, and the user's next step, usually `exo:ship`. Unproven: `Repro`, `Expected`, `Actual` and `Hypotheses`. Proof lines and commit hashes stay in the handoff.