debug

name	debug
description	Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes. Enforces root cause investigation before fixing. No guessing, no shotgun debugging. Hard stop after 3 failed hypotheses. Use when: tests fail, errors appear, behavior doesn't match expectations, or something "just broke."
version	1.0.0

Debug

The Rule

No fixes without root cause investigation. If you can't explain WHY it's broken, you can't fix it. You're just guessing.

The Loop

Phase 1: Investigate

• Collect symptoms: what fails, when, error messages, stack traces
• Read the relevant code (not just the error line, the surrounding context)
• Check git log for recent changes in affected files
• Reproduce the issue. If you can't reproduce it, you can't verify a fix.

Phase 2: Pattern match

Does this look familiar?

Pattern	Typical signal
Race condition	Intermittent, timing-dependent, works in debug mode
Nil/null propagation	Crashes on missing data, works with full records
State corruption	Works first time, breaks on retry or concurrent use
Integration failure	Works locally, breaks with external service
Config drift	Works in one environment, not another
Stale cache	Works after restart, breaks after time passes