Root cause investigation before bug fixes. Auto-triggers on bug reports, errors, crashes, and unexpected behavior. Enforces diagnosis before code changes.
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION. "I think I know the issue" is not evidence.
Identify: What (exact error/behavior), When (steps), Where (file/line/component), Since when (git log). Ask one question at a time.
Based on symptoms, possible causes:
1. [Hypothesis A] -- [reasoning]
2. [Hypothesis B] -- [reasoning]
3. [Hypothesis C] -- [reasoning]
Investigating hypothesis 1 first because [reason].
Add minimal diagnostic code only: log statements, assertions, print values. The only code change allowed during investigation.
Run reproduction steps with diagnostics. Record: actual vs. expected, where divergence occurs.
| Class | Description | Next Step |
|---|---|---|
| A: AC Gap | Not covered by any AC | Add AC via discover, then fix |
| B: Test Gap | AC exists, tests insufficient | Write missing test, then fix |
| C: Logic Error | Tests exist, implementation wrong | Write regression test, then fix |
## Root Cause Analysis
**Classification:** [A / B / C] -- [class name]
**Cause:** [description]
**Evidence:** [what proved this]
**Code:** [file path and line number]
Proceed to fix? [Yes / Need more investigation]
atdd-kit:discover to add missing ACatdd-kit:atdd with regression testAfter 3 failed fixes: STOP. Do NOT attempt fix #4.
| Thought | Reality |
|---|---|
| "I think it's this" | Thinking is not evidence. Investigate. |
| "Quick fix for now, investigate later" | "Later" never comes. Investigate NOW. |
| "Just try changing X" | Guessing wastes time. Form a hypothesis. |
| "This is obviously the cause" | "Obviously" is a red flag. Prove with evidence. |
| "Let me just try this fix" | NO. Complete Step 5 first. |
| "I've seen this before" | Past experience informs hypotheses, not conclusions. Verify. |
| "It's probably a race condition" | "Probably" requires evidence. |