troubleshooting-rca

Activation gate (anti-noise)

Activate when:

• There is an error message, failing test, crash, regression, unexpected behavior, or logs.

Skip when:

• User requests implementation from scratch and no failure exists yet.

Procedure

1. Restate symptom + expected behavior.
2. Collect minimal repro:

- Command, input, environment, last known good commit.

1. Hypotheses (max 3) ranked by likelihood.
2. Test each hypothesis with the smallest possible check.
3. Before Fix: Root cause must be clearly stated; one minimal verification step must be given. Then: Fix + verify with test/run.
4. Add a prevention note (test, guard, logging).

Output

• Symptom → Most likely cause → Fix → Verification command(s).