From 0f28af9f4361f88cde915b9b85a3d26848d40e92 Mon Sep 17 00:00:00 2001 From: "bert.hausmans" Date: Sun, 10 May 2026 00:16:31 +0200 Subject: [PATCH] docs(claude): codify audit-before-assume principle as diagnostic discipline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New section in CLAUDE.md after "Order of work for each new module". Three consecutive incidents in the timetable sprint led to formalising this principle: - B1 (controller assumed buggy, seeder was wrong) — Phase A's schema-verify gate against SCHEMA.md:1285 + RFC §10.2 inverted the fix direction. - B5 (enum-shape assumed drifted, decimals were wrong) — Phase A's field-by-field response audit caught the actual decimal-as-string drift before any "fix" against the wrong hypothesis was written. - Timetable UX (test-passing layer diverged from prototype) — the mechanical-vs-UX split surfaced via browser test, not via the 389-test suite which all agreed with the buggy state. Pattern across all three: the initial hypothesis was wrong. The fix prompts ALL gated Phase A as STOP-and-report; the schema/contract/ prototype audit was reviewed before any code was written. Codifying this as an explicit project principle so future fix prompts inherit the gate by default. Co-Authored-By: Claude Opus 4.7 (1M context) --- CLAUDE.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) 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.