CLAUDE.md

@@ -317,6 +317,32 @@ allowed only with a `TODO TECH-*` reference to a backlog item.
 13. Vue page component in `src/pages/[module]/`
 14. Add route in Vue Router
 
+## Diagnostic discipline: audit before assume
+
+When debugging or fixing any bug, the first action is to verify the
+canonical model against the artifact in question — not to write a fix
+based on the symptom or hypothesis.
+
+This applies to:
+
+- Schema drift (verify the resource shape against the Zod schema, line
+  by line)
+- Filter logic (verify the data model in SCHEMA.md before assuming a
+  controller is wrong)
+- UX divergence (verify the prototype line-by-line, not via spot check)
+- Test failures (verify the assertion matches the documented contract,
+  not the current implementation)
+
+Phase A of every fix prompt is STOP-and-report. No code is written
+before the audit is reviewed.
+
+This principle was formalised after three consecutive incidents where
+initial hypotheses were wrong and the audit gate caught them: B1
+(controller assumed buggy, seeder was wrong), B5 (enum-shape assumed
+drifted, decimals were wrong), and timetable UX (test-passing layer
+diverged from prototype, mechanical-vs-UX split surfaced via browser
+test).
+
 ## User Documentation (VitePress)
 
 End-user documentation lives in /docs/ as a VitePress site.