Diagnose

Features

• Structured debugging loop: Reproduce, minimize, hypothesize, instrument, fix, regression-test.
• Emphasis on building reliable feedback loops for testing hypotheses.
• Guidance on handling non-deterministic bugs and performance regressions.
• Clear steps for cleanup and post-mortem analysis.

Use Cases

• Use when a user reports a bug or performance issue that is difficult to reproduce.
• Use when a system is broken, throwing errors, or exhibiting unexpected behavior.
• Use to systematically investigate and resolve complex, intermittent bugs.
• Use to proactively identify and fix performance regressions.

Non-Goals

• Identifying the root cause without a reproducible feedback loop.
• Simply fixing a bug without understanding the underlying cause.
• Performing code reviews or architectural improvements (though it may identify needs for them).

Workflow

1. Build a feedback loop (e.g., failing test, CLI script, harness).
2. Reproduce the bug using the loop, capturing the exact symptom.
3. Generate and rank 3-5 falsifiable hypotheses.
4. Instrument code to test hypotheses, changing one variable at a time.
5. Write a regression test (if possible), fix the bug, and verify the fix.
6. Clean up instrumentation, delete prototypes, document the root cause, and consider preventative measures.

Practices

• Debugging methodology
• Hypothesis testing
• Feedback loops
• Regression testing