/diagnose — Structured differential diagnosis

Investigate a bug systematically by gathering evidence, forming multiple hypotheses, and testing each before proposing any fix. This prevents the "guess and fix" anti-pattern.

Steps

1. Gather the symptom from $ARGUMENTS or ask the user. Document:

- What's happening (the observable failure) - What's expected (the correct behavior) - When it started (if known) - Any user-provided log evidence

1. Collect evidence — read logs, error output, and relevant source code:

- Read the FULL log, not just the error line - Search for related error patterns in the codebase - Check docs/LINEAR_SNAPSHOT.md for related tracked bugs - Check recent git changes: git log --oneline -20 and git diff HEAD~5

1. Form hypotheses — generate 2-4 distinct possible causes:

`` Hypothesis 1: [cause] — Evidence for: [X] | Evidence against: [Y] Hypothesis 2: [cause] — Evidence for: [X] | Evidence against: [Y] Hypothesis 3: [cause] — Evidence for: [X] | Evidence against: [Y] ``

1. Test each hypothesis — for each one, find confirming or disconfirming evidence:

- Use Task agents to investigate multiple hypotheses in parallel when possible - Search for code paths, check configurations, read documentation - Each hypothesis must have a verdict: CONFIRMED, RULED OUT, or INCONCLUSIVE

1. Report findings in structured format:

``` ## Diagnosis: [symptom summary]

### Evidence Collected - [evidence 1 with file:line] - [evidence 2 with file:line]

### Hypotheses Tested 1. [hypothesis] — [CONFIRMED/RULED OUT/INCONCLUSIVE] Evidence: [what confirmed or ruled it out] 2. [hypothesis] — [CONFIRMED/RULED OUT/INCONCLUSIVE] Evidence: [what confirmed or ruled it out]

### Root Cause [Most likely cause with supporting evidence]

### Recommended Fix [Specific fix with file:line targets] [What could go wrong with this fix]

### What This Is NOT [Ruled-out causes — prevents revisiting dead ends] ```

1. Record the verdict on the tracked issue. A diagnosis that stays in the

session is lost — the next session re-reads the same unconfirmed theory and re-does the same work. If the bug is tracked in Linear:

```bash linear issue comment add ENG-123 -b "Root Cause: CONFIRMED — <file:line>

Reproduced by: <exact command, steps, or test that shows the failure>

Evidence: <what confirmed it, with file:line or log output>

Ruled out: <hypotheses eliminated, and what eliminated them>

Observed at: <short sha> on <branch>" ```

- Promote the issue's root cause to CONFIRMED only when a hypothesis reached that verdict with evidence. This status is /fix-issue's entry condition — writing it on a theory defeats the gate. - If every hypothesis was INCONCLUSIVE, say so on the issue and record the ruled-out list anyway. Knowing where the cause is not is a real result and it stops the next session repeating the dead ends. - If the bug is not tracked yet, use /document-bug to create the issue first.

1. Do NOT implement the fix — present the diagnosis and let the user decide.

Critical Rules

• Follow user evidence first. If the user provides log evidence pointing to cause X, investigate X before proposing alternative theories.
• No speculative fixes. Do not propose a fix until at least one hypothesis is confirmed with evidence.
• Quote evidence. Every claim must reference specific file:line or log output.
• Rule out before concluding. The first plausible theory is often wrong. Test at least 2 hypotheses.

Notes

• This skill is investigation-only — it does not modify source files. Writing the

verdict to the issue is not a source change and is not optional

• Use Task agents for parallel investigation when hypotheses are independent
• If all hypotheses are inconclusive, say so and suggest additional diagnostic steps
• Use /document-bug to log findings in Linear if the bug isn't already tracked
• This skill is the only transition from an UNCONFIRMED root cause to a

CONFIRMED one. /fix-issue will not fix a bug that has not been through it