diagnose

name	diagnose
description	Systematic debugging loop for hard bugs and performance regressions. Use when something is broken and you don't know why, when behavior is inconsistent, or when error messages are unclear. Follows reproduce → minimise → hypothesise → instrument → fix → regression-test.
argument-hint	[bug description or error message]

Systematic Debugging

"Debugging is twice as hard as writing the code in the first place." — Brian Kernighan

Philosophy

Never guess at fixes. The #1 debugging anti-pattern is shotgun debugging — changing multiple things hoping one works. This skill enforces a disciplined loop: understand before fixing.

Workflow

Copy this checklist and track your progress:

Diagnosis Progress:
- [ ] Step 1: Reproduce reliably
- [ ] Step 2: Minimize the case
- [ ] Step 3: Form hypotheses
- [ ] Step 4: Instrument and test
- [ ] Step 5: Fix the root cause
- [ ] Step 6: Regression test

Step 1: Reproduce

• Find the minimal steps to trigger the bug
• Document exact reproduction steps
• If intermittent: identify conditions that increase probability
• Write a test that reproduces the bug (becomes your regression test)
• Run reproduction at least twice to confirm consistency

Step 2: Minimize

Reduce to the smallest possible case:

• Remove unrelated code paths
• Simplify input data
• Reduce configuration to essentials
• Isolate the failing component

Step 3: Form Hypotheses

List at least 2 hypotheses. For each:

• What evidence supports it?
• What evidence contradicts it?
• How to test it?

Order by likelihood. The obvious cause is often wrong.

Step 4: Instrument and Test

For each hypothesis (in order):

1. Add minimal logging/monitoring to test it
2. Run the reproduction
3. Analyze the output
4. Confirmed? → proceed to fix. Denied? → next hypothesis

One hypothesis at a time. Change one thing, observe, repeat.

Step 5: Fix

• Fix the root cause, not the symptom
• No try-catch patches, no error suppression
• Apply Surgical Changes: fix only what's broken
• Apply Simplicity First: simplest fix that addresses root cause

Step 6: Regression Test

• The reproduction test from Step 1 now passes
• Add edge case tests
• Run full test suite
• Document: bug, root cause, fix, lesson learned

Output

## Diagnosis: [Bug Description]

### Reproduction
1. [Step 1] 2. [Step 2] 3. [Step 3]

### Root Cause
[Confirmed hypothesis]

### Fix
[What was changed and why]

### Regression Test
[Test description or link]

Anti-Patterns

• Shotgun debugging — Changing multiple things at once
• Fixing symptoms — Patching error messages instead of root causes
• Skipping reproduction — Can't verify fix without it
• Assuming the obvious — Verify with instrumentation

The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

If you haven't completed root cause investigation, you cannot propose fixes.

Multi-Component Diagnosis

When the system has multiple components (e.g., API → service → database), BEFORE proposing fixes, add diagnostic instrumentation at EACH component boundary:

For EACH component boundary:
- Log what data enters the component
- Log what data exits the component
- Verify environment/config propagation
- Check state at each layer

Run once to gather evidence showing WHERE it breaks.
THEN analyze evidence to identify the failing component.
THEN investigate that specific component.

The 3-Fix Rule

If you've tried 3 or more fixes and none worked, STOP. This is not a stubborn bug — it's likely an architectural problem.

When 3+ fixes fail:

1. STOP attempting fixes
2. Question the architecture: Is the fundamental pattern sound?
3. Each fix reveals new problems in different places = architectural issue
4. Discuss with your human partner before attempting more fixes

This is NOT a failed hypothesis — this is a wrong architecture.

Red Flags — STOP and Return to Phase 1

If you catch yourself thinking:

• "Quick fix for now, investigate later"
• "Just try changing X and see if it works"
• "Add multiple changes, run tests"
• "It's probably X, let me fix that"
• "One more fix attempt" (when already tried 2+)

ALL of these mean: STOP. Return to root cause investigation.

Integration

• Use /tdd after diagnosis to implement the fix
• Use /grill if the bug reveals a misunderstanding of requirements
• Use /zoom-out if the bug spans multiple modules