/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

2. 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

3. 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]
   

4. 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

5. 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]
   

6. 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:

   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.

7. 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