debugging-policylisted

# Debugging Policy (Root-Cause Methodology) ## Activation Scope - Apply whenever investigating a bug, failure, crash, regression, or unexpected behavior. - Owns the reproduce-isolate-fix methodology and root-cause discipline. --- ## Core Principle - Fix the root cause, not the symptom. - Understand why the bug happens before changing any code. - Do not guess-and-check randomly; each step must be driven by evidence. --- ## Methodology 1. Reproduce: establish a reliable, minimal reproduction. If it cannot be reproduced, gather more evidence first. 2. Observe: collect facts - error messages, stack traces, logs, inputs, and actual vs expected behavior. 3. Form a hypothesis: a specific, falsifiable theory of the cause based on the evidence. 4. Isolate: narrow the surface using bisection, logging, or targeted breakpoints until the faulty unit is identified. 5. Confirm: prove the hypothesis (the failing case maps to the identified cause) before fixing. 6. Fix: address the underlying cause at the right layer. 7. Verify: add a regression test that fails before the fix and passes after (per testing-policy), then run the relevant suite. 8. Review: assess whether the same class of bug exists elsewhere. --- ## Investigation Rules - Read the actual error and the actual code path; do not assume from names or memory. - Change one variable at a time so cause and effect stay clear. - Reproduce before fixing and verify after; never declare a fix without confirming it. - Prefer the sm