diff --git a/CLAUDE.md b/CLAUDE.md index 83e75554..01103de4 100644 --- a/CLAUDE.md +++ b/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.