diagnose git:20261006.0e04d6fA

Immutable. This exact content never changes and is served at /api/v1/blob/04facdd5141a00f1.

---
name: diagnose
description: Reproduce-first debugging, a red-capable repro before any hypothesis or edit. - Use when investigating a bug, a failing test, unexpected behavior, or a crash. Triggers on "diagnose", "debug this", "why is this failing", "not working", "broken", "repro", "root cause".
user-invocable: true
---

# Diagnose: loop first, hypothesis second

The iron rule: **build a feedback loop that shows the failure BEFORE you form a hypothesis or touch the code.** Guess-and-check edits without a repro destroy evidence and can't prove a fix.

## 1. Reproduce: the red-capable loop

- Produce a command you can re-run that FAILS now because of this bug and will pass once it's fixed.
- It can be a failing test (best: it becomes the §6 bug-fix test), a script, or a curl/CLI invocation.
- Shrink it to the fastest reliable red.
- Cannot reproduce? That IS the current task: instrument until you can. Never edit code "to see if it helps" before a repro exists.

## 2. Observe: tagged instrumentation

- Add logging with a per-session tag: `[DEBUG-x7k2]` (any 4-char id). Tagged output is greppable in noisy logs and strippable in one sweep.
- Log VALUES at boundaries (inputs, outputs, branches taken), not "got here".
- Prefer widening observation over narrowing guesses.

## 3. Hypothesize: falsifiable, one at a time

- State the hypothesis with its prediction BEFORE testing it: "If X is the cause, then changing/logging Y will show Z."
- Run the loop. Prediction wrong: the hypothesis is dead. Form the next one from the new evidence.
- Never stack a second speculative edit on top of a first.
- Sharp red signals (a crash with a stack) outrank soft symptoms. Chase the loudest signal first (Loud Failures doctrine: the crash site is a gift).

## 4. Fix and prove

- The repro from step 1 is the proof: red before the fix, green after, run in THIS session. Never declare fixed on reasoning alone.
- Then run the touched test files for collateral damage, as `npm test -- <file>` from that package's folder, never an unscoped suite.

## 5. Clean up

- Strip every `[DEBUG-xxxx]` line (grep the tag to find them all). Never leave tagged debug output in the tree.
- Keep the repro test.
- Done-criteria: repro test green with the touched test files, tag grep returns nothing, no unrelated lines changed.