# Diagnose

Root-cause a failing or wrong empirical result with a disciplined reproduce → minimise...

- Repository: https://github.com/pedrohcgs/claude-code-my-workflow (1676 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-09-27
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add pedrohcgs/claude-code-my-workflow --skill diagnose -g -a claude-code -y`
Codex: `npx skills add pedrohcgs/claude-code-my-workflow --skill diagnose -g -a codex -y`
Cursor: `npx skills add pedrohcgs/claude-code-my-workflow --skill diagnose -g -a cursor -y`
Gemini CLI: `npx skills add pedrohcgs/claude-code-my-workflow --skill diagnose -g -a gemini-cli -y`

## Description

Root-cause a failing or wrong empirical result with a disciplined reproduce → minimise → hypothesise → instrument → fix loop, instead of guessing-and-poking. Use when the user says "why is my regression wrong", "this number changed", "my script errors out", "the result won't reproduce", "debug this", "this estimate looks wrong", or "it worked yesterday". Tuned for research code (R/Stata/Python): type coercion, NA/merge blow-ups, factor levels, clustering/SE choices, weighting, collinearity/convergence, seeds, package-version drift. Use `--no-fix` to localize the root cause without editing shared or load-bearing files.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# /diagnose, Root-Cause a Wrong or Failing Result

Find *why* an analysis errors, returns the wrong number, or won't reconcile, with a structured debugging loop rather than scattershot edits. Adapted from the `diagnose` pattern in [mattpocock/skills](https://github.com/mattpocock/skills), reshaped for empirical research code where the bug is usually a *silent* wrong number, not a crash.

The discipline: **never edit before you can reproduce, and never fix before you can explain.** A guessed fix that makes the symptom disappear without a named root cause is how a wrong number gets *laundered* into a published table.

## When to use

- A regression / estimate returns a value you can't explain, or one that changed when nothing should have.
- A script errors out and the stack trace doesn't point at the real cause.
- A result "won't reproduce", different number on re-run, on another machine, or after a package update.
- A replication claim fails `/audit-reproducibility` and you need to localize *which* step drifted.

**Diagnose is symptom-driven and single-target: ONE wrong number / ONE failing run.** Use a sibling instead when the job is different:

- [`/audit-reproducibility`](../audit-reproducibility/SKILL.md), verify *all* numeric claims in a manuscript against current code (claim-driven, whole-paper). If you have one FAILing claim and want to localize which pipeline step produced it, `/audit-reproducibility` hands off *to* `/diagnose`; if you want to re-check every table number, start there.
- [`/review-r`](../review-r/SKILL.md), code-quality review with **no specific symptom**.
- [`/capture-environment`](../capture-environment/SKILL.md), snapshot the environment when version/seed drift is the suspect.

## Phases

### Phase 0, Pin the symptom (expected vs. actual)

State the bug as a falsifiable gap before touching anything:

The rest: https://github.com/pedrohcgs/claude-code-my-workflow/blob/HEAD/.claude/skills/diagnose/SKILL.md