# Diagnose

> Find root cause by running the red loop from `prove-the-failure` and changing one variable at a time — never by reading the code and reasoning about it. Outputs a written cause with file and line evidence. Use after containment, before any repair is designed.

- Skill: `cleanexpo/diagnose` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cleanexpo/diagnose`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cleanexpo/diagnose/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: cleanexpo (https://skillmd.com/u/cleanexpo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cleanexpo/diagnose

---


# diagnose

**Diagnose against the loop, not against a reading of the code.** A cause derived from reading is a hypothesis wearing a conclusion's clothes. A cause is proven when you can turn the loop red and green at will by changing the thing you claim is responsible.

## Phase 1 — Confirm the loop is measuring the right failure

Run it. Observe.

- [ ] It produces the reported failure mode, not a nearby different one
- [ ] It reproduces consistently, or at the pinned rate
- [ ] The exact symptom is captured — error text, wrong value, timing

If the loop is red for a different reason than the report, you have found a second failure. Stop and split them.

## Phase 2 — Minimise

Shrink to the smallest scenario still going red. Remove inputs, callers, config, data, and steps one at a time, rerunning after each cut. Keep only what is load-bearing.

Done when removing any remaining element turns the loop green.

## Phase 3 — Hypothesise, then rank

Generate 3–5 hypotheses **before testing any**. Each must be falsifiable and predict a direction:

> "If X is the cause, then changing Y turns the loop green, and changing Z makes it worse."

Rank them. Cheap-and-likely first.

## Phase 4 — Instrument, one variable at a time

Each probe tests exactly one ranked prediction.

1. **Debugger or REPL** where available — one breakpoint beats ten logs.
2. **Targeted logs** at the boundary that distinguishes two hypotheses.
3. Never "log everything and grep".

Tag every debug log uniquely (`[DEBUG-a4f2]`) so cleanup is one grep.

## Phase 5 — Prove it

The cause is proven when you can **turn the loop red and green on demand** by toggling the claimed cause, and no other change is required.

Correlation is not enough. If the loop goes green when you change two things, you have not finished.

## Completion — a written cause

- [ ] **Cause stated in one sentence**, in plain language
- [ ] **File and line evidence** — the exact location, quoted
- [ ] **Toggle demonstrated** — loop goes red and green by changing that thing alone
- [ ] **Rejected hypotheses listed**, each with what ruled it out
- [ ] **All debug instrumentation removed**

The rejected list matters. It is the cheapest thing to write now and the most expensive to reconstruct later, and `classify` uses it to judge novelty.

## Stop conditions

**No red loop, no diagnosis.** If `prove-the-failure` did not complete, go back. Do not proceed on a described failure.

**If the cause cannot be proven by toggle,** say so and report the strongest hypothesis as *unproven*, with what would prove it. An unproven cause is a valid outcome — it goes to `incident-memory` and it forces `classify` to treat the failure as novel.

## Next

`classify` — known or novel, and how wide the blast radius is.