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".
Installs into .claude/skills of the current project.
Are you the author of Diagnose?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/itw-creative-works-diagnose)
---
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.
