Compliance Hub · Mandatory Pills Distinction
Two Kinds of
"Mandatory"
The tool's MANDATORY pill conflates two genuinely different obligations: "the product must comply" vs "this text must appear in the manual." Three decisions to fix it.
The core insight: the standards already make this distinction — every "shall" clause has a subject, and the subject is either the build or the document. We're not inventing a framework. We're labelling one the standards encode but never named.
🔴 MUST COMPLY
🟠 MUST APPEAR
🟢 RECOMMENDED
⚪ OPTIONAL
📋 3 decisions needed
🔴
D1 — How many pill tiers?
The existing binary MANDATORY / RECOMMENDED hides a real split. A flue clearance the installer must achieve and a warning the manual writer must print both just say "MANDATORY." Split it: 2 → 3 → 4 pills.
📄
D2 — Where the obligation physically lives
The tool says nothing about where a requirement lives — printed in the box, stamped on the product, or a QR supplement. No blanket "paper copy in the box" rule exists; it's per-standard. Give documentation & marking a home.
🔗
D3 — Copy Builder + Manual Review
Both tools sweep the same corpus and surface the same requirements — they differ only in input (product type vs uploaded PDF) and output framing (draft copy vs PASS/FAIL). One engine makes the D1/D2 work pay off everywhere.
The core insight
Standards already make this distinction — we're just labelling it.
Australian/NZ standards inherit a precise four-level verbal-form hierarchy from ISO/IEC Directives Part 2 — shall / should / may / can. Critically, the discriminator between the owner's two "mandatory" types is already in the text: read what the "shall" clause governs. "The appliance shall withstand…" is a requirement on the build. "Installation instructions shall be provided stating…" is a requirement on the document. Same word, different target. The framework we build formalises a distinction the standards make implicitly through clause subject.
The recommended package at a glance
- D1 → Option B now (3 pills), Option C next (4 pills). Split MANDATORY into MUST COMPLY + MUST APPEAR first; add an OPTIONAL tier for
may/informative content second.
- D2 → Option B now (dedicated Documentation & Marking section), enrich toward Option C (location badges) next.
- D3 → Option C now (shared engine, two familiar pages), Option B (full merge) optional later.
- Why it hangs together: D3's shared engine is the foundation — once Build and Review run through one taxonomy, the D1 pills and D2 sections are implemented once and show up consistently everywhere.
Axis 1 — Strength: the verbal-form hierarchy (ISO/IEC Directives Part 2)
| Word | Meaning | Obligation | Conformance impact |
|---|
| shall |
Requirement |
Mandatory to conform |
Must be met in all cases to claim conformity. (When the standard is called up by law — NCC, plumbing/gas/electrical regs — "shall" becomes legally mandatory.) |
| should |
Recommendation |
Encouraged, not required |
Best practice; non-compliance is permissible. |
| may |
Permission |
Optional / allowed |
A liberty or option — e.g. "instructions may be supplied via a QR code in addition to printed text." |
| can |
Possibility / capability |
Descriptive |
Statement of fact or ability — not an obligation at all. |
The subtlety: "shall" ≠ "must"
Standards deliberately avoid "must." A "shall" carries a hidden "[to comply]" because standards are technically voluntary documents. Two tiers of mandatory worth noting: shall in a standard = mandatory for conformity; shall in a standard referenced by law = mandatory by law. (This is the seed of a possible phase-2 "Regulatory vs Standard" badge — not a pill.)
Axis 2 — Target: what does the "shall" clause act upon?
This is the owner's insight, and it's grammatical: read the subject of the clause.
Target = the build
"Mandatory Compliance"
"The appliance shall withstand…" · "Flue terminal clearances shall comply with Table 6.x"
A requirement on the product or installation — something the installer or the product must physically achieve.
Target = the document
"Mandatory Copy"
"Installation instructions shall be provided stating…" · "Instructions shall state minimum clearances"
A requirement on the documentation — something the manual writer must put on the page.
The two axes → the four pills (research §6 framework)
| Pill | Maps to | Target | Plain English |
|---|
| MUST COMPLY |
normative shall |
The build |
"Installation / product must meet this." |
| MUST APPEAR |
normative shall |
The document |
"This must be printed in the manual." |
| RECOMMENDED |
should |
Either |
"Good practice — encouraged." |
| OPTIONAL |
may / informative |
Either |
"Permitted option / guidance." |
Why this is safe to ship
Two-colour grouping keeps the at-a-glance binary the owner already has: red + amber = the mandatory family, green + grey = the non-mandatory family. The precision is added without losing the gestalt. Confidence: shall/should/may definitions VERIFIED; specific clause numbers INFERRED pending corpus verification.
The two existing pills
- MANDATORY — red. Every
shall-derived item. The build-vs-document distinction is invisible.
- RECOMMENDED — green. Every
should-derived item.
Where the current system misleads — 🔥 gas hot water heater
A single red MANDATORY list mixes two fundamentally different things:
MANDATORY "Flue terminal clearances shall comply with Table 6.x" — a build requirement (the installer's job)
MANDATORY "Installation instructions shall state the minimum clearances" — a document requirement (the manual writer's job)
The user can't tell that the first is something the installer must physically achieve and the second is something the manual writer must put on the page. Both just say "MANDATORY."
The two limitations
1
MANDATORY conflates build and document. Manual authors keep mis-reading product requirements as "things to copy into the manual" and vice versa. This is the originating problem.
2
No home for may / informative content. Genuinely optional content (QR supplements, informative appendices) either gets mislabelled as RECOMMENDED or dropped — so the reds lose weight through over-warning.
Key insight — no blanket rule, per-standard distributed
The general principle "instructions must be provided/supplied with the product" appears as shall-level requirements in product standards. But no single overarching AU/NZS clause says "a paper copy must always be in the box." It is distributed across individual product standards — and newer editions increasingly allow digital/QR access. So whatever we build must be driven by the specific standard, not hard-coded.
Three distinct physical / locational obligation types
📦
Physically supplied (in the box). "A copy of the installation instructions shall be supplied with the appliance." Per-standard; modality varies.
🏷️
On the product. Rating/data plates, RCM mark (electrical, AS/NZS 4417), WaterMark symbol (plumbing) — these must be physically on the unit. VERIFIED
🔗
Supplementary access. QR code / web address provisions — permitted in addition to (a may permission), generally not as the sole reference.
By regime — what's verified vs inferred
- 🚿 WaterMark (plumbing). Mandatory scheme; the WaterMark symbol must be displayed on the product. Installation instructions typically required by the referenced product standard. symbol-on-product VERIFIED "paper in box" INFERRED
- ⚡ Electrical (EESS + AS/NZS 60335). Mandatory RCM marking on product; a technical construction / compliance file is retained documentation, not necessarily shipped. "Instructions shall be provided" lives in the product standard. RCM VERIFIED clause INFERRED
- 🔥 Gas (AS/NZS 5601.1 install + AS/NZS 5263 appliance). Appliance data plates mandated; compliance label / SDoC before install; instructions-supplied clause in the appliance General Requirements part. data plate VERIFIED clause INFERRED
- NCC Part A5. Evidence-of-suitability documentation must be prepared and retained — compliance evidence, distinct from the consumer manual. VERIFIED
Corpus-verification dependency
Before any pill or section auto-tags a specific clause, the INFERRED clause-level items (instructions-shall-be-supplied, marking clauses, location modality) must be Opus-verified against the ingested corpus per the project's no-citation-no-claim rule. The classification attributes are only as trustworthy as that pass.
The existing binary MANDATORY / RECOMMENDED conflates two genuinely different obligations: "the product must do X" vs "this text must be in the manual." How far do we split that out? On a 🔥 gas hot water heater, a flue-clearance build requirement and an instructions-content document requirement currently both read "MANDATORY" — the user can't tell whose job each is. The two axes (strength × target) support up to four pills, grouped red+amber = mandatory, green+grey = not.
A Keep 2 pills (MANDATORY / RECOMMENDED) — no change; build-vs-document stays invisible. Cost: none. Baseline / do-nothing anchor only.
B 3 pills — split MANDATORY into MUST COMPLY (build) + MUST APPEAR (document), keep RECOMMENDED. Delivers the core ask at lowest viable cost. Backend Medium, frontend Low–Med. — recommended phase 1
C 4 pills — add OPTIONAL / GUIDANCE for may + informative content. Full normative accuracy, kills over-warning. Backend High (needs may/informative detection). — phase 2 destination
The tool surfaces nothing about where an obligation physically lives — printed in the box (📦), stamped on the product (🏷️ rating plate / RCM / WaterMark symbol), or a QR/web supplement (🔗). For a ⚡ electrical appliance, "rating label shall show the RCM mark" is on-product, while "instructions shall include rated voltage" is in-manual — different homes. Respect the finding: there's no blanket "paper copy in the box" rule, so whatever we build must be driven by the specific standard.
A Fold into MUST APPEAR automatically — any "instructions shall be supplied" clause rides the D1 amber pill. Cheapest, but re-conflates "must be written" with "must be physically delivered/located." Stopgap only.
B Dedicated "Documentation & Marking" section — a standalone block collecting instructions, data-plate content, compliance-mark display, warnings; pills apply within it. Mirrors how regulators split the streams. Backend/frontend Medium. — recommended
C Inline location badges — keep items in place, add a sub-badge per item: 📦 Supplied · 📖 In manual · 🏷️ On product · 🔗 Supplementary. Most granular and honest. Backend High (per-item location, much inferred). — phase 2 enrichment
Both tools sweep the same corpus and surface the same requirement set — they differ only in input (pick a product type vs upload an existing PDF) and output framing (draft copy vs PASS/PARTIAL/FAIL gap analysis). For the 🔥 gas heater, the requirement list should be identical across both; today they can drift and label differently, which undercuts the D1/D2 pill work. The taxonomy investment only pays off if both surfaces render the same pills and sections.
A Keep separate tools — two pages, two codebases, two output formats. No migration risk, but duplicated corpus-sweep logic drifts out of sync and breaks taxonomy consistency. Not recommended.
B Full merge into one "Compliance Copy" tool with a mode toggle (Build new / Review existing). Single source of truth, best workflow elegance — but a bigger combined-UI release and migration risk. Strongest if there's appetite for the merge.
C Separate pages, shared engine + identical output format — two familiar URLs rebuilt on one corpus-sweep service + one rendering component. ~90% of B's benefit, low migration risk, clean path to B later. — recommended
Why D3 Option C comes first
One engine, one taxonomy, identical output. Once Build and Review run through a single corpus-sweep service and rendering component, the D1 pills and D2 documentation section only have to be implemented once — and they appear consistently across both surfaces. Doing D3 cheaply (Option C, no disruptive merge) first de-risks D1 and D2. Everything is phased so phase 1 ships value and phase 2 adds accuracy without rework.
Phase 1 — ship value
D1-B + D2-B + D3-C
3 pills (MUST COMPLY / MUST APPEAR / RECOMMENDED) — solves the originating two-mandatories confusion.
Documentation & Marking section with a coarse location badge (📖 in manual / 🏷️ on product / 📦 supplied).
Shared engine behind both Copy Builder and Manual Review — two familiar pages, identical taxonomy.
Phase 2 — add accuracy
Upgrade to D1-C + D2-C
4th pill — add OPTIONAL / GUIDANCE for may + informative content once the corpus has been swept for it.
Full location badges — enrich to per-item granularity (add 🔗 Supplementary + confidence flags) once location data is verified.
Optional later: D3 Option B full merge; a "Regulatory vs Standard" badge on MUST COMPLY items.
Build order — why this sequence
1
D3-C first (shared engine). The real work either way is the one corpus-sweep service + rendering component. Build it once, behind the scenes, no user relearning.
2
D1-B + D2-B on top. Add the target: build|document attribute and the Documentation & Marking section — they now render identically in both surfaces because the engine is shared.
3
Then D1-C + D2-C. The expensive part — may/informative detection and per-item location — graduates the framework to full normative accuracy once the attributes are bedded in.
Hard dependency
Before any pill/section auto-tags a specific clause, the INFERRED clause-level items must be Opus-verified against the ingested corpus (no citation = no claim). The strength, target, and location attributes are only as trustworthy as that verification pass.
🏷️
Pill names — happy with MUST COMPLY / MUST APPEAR?
Alternatives exist: "REQUIRED (BUILD)" / "REQUIRED IN MANUAL", or "INSTALLATION REQUIREMENT" / "DOCUMENTATION REQUIREMENT". Parallel verb-led labels read best — but your call on wording.
🔢
Phasing — ship 3 pills first, or go straight to 4?
The recommendation is B then C to bound the may/informative classification cost. If you'd rather do the full 4-pill sweep in one go, that changes the phase-1 scope.
📄
Documentation section vs inline badges?
D2-B (a dedicated section) vs D2-C (inline location badges) is partly a visual-design preference. Any strong feeling on which mental model fits how authors actually work?
🔗
Appetite for the full Copy Builder / Review merge?
D3-C keeps two pages; D3-B merges them into one tool. C is the low-risk pick, but if you want the single-tool workflow now, that's a bigger but cleaner release.
⚖️
Regulatory vs Standard badge — phase 2?
The "shall-in-law vs shall-in-standard" nuance could become a small badge on MUST COMPLY items. Held as phase-2 to avoid overloading the first release — agree, or want it sooner?
🔍
Anything missing?
Any obligation type, product example, or edge case the four-pill framework doesn't capture — or anything that seems structurally wrong about the framing.
How to respond
Reply directly in Teams with your answers to D1–D3 and any feedback above. No need to use the deck format — a numbered list of decisions + any comments is fine. The "Copy summary" button below the decisions captures your selections and notes as plain text you can paste straight in.