Skip to content

ADR-v2-114 — Acronym / Glossary First-Use Manager

Status: Accepted (2026-07-02) · Wave M Context links: hotwords, itn, spelling, [[adr-v2-109-style-consistency-enforcer]], [[adr-011]]

Context

Wave M research (#10) — track defined terms in the current document; on first mention expand "World Health Organization (WHO)", then let the user say "W-H-O" and inject the acronym; and flag an undefined acronym that was never expanded. Contextual biasing (Hotwords), ITN, and Phonetic Spelling handle recognition/formatting; none manages document-scoped acronym state (define-on-first-use, later contraction, undefined-acronym warnings). A small, distinct text-intelligence layer. Anchor: the "define acronyms on first use" convention is a hard rule in scientific/technical/medical style guides; acronym-consistency checkers exist as static tools (LaTeX glossaries/acro, journal checkers) but not in any live dictation flow.

Decision

Add an opt-in Acronym/Glossary Manager: [acronyms] enabled=false. Pure core in acronyms/glossary.py: AcronymState with observe(text) (learn "Full Name (ACR)" definitions already written), define(acr, full) (register a known expansion for first-use), resolve(term) (expand on first use, contract after), and audit(doc) → warnings for acronyms used but never defined. Pure regex/dict; no model. OFF by default.

Consequences

  • Consistent define-on-first-use and undefined-acronym warnings, hands-free.
  • Pure state machine → fully testable.
  • Distinct from Hotwords/ITN (document-scoped acronym state vs recognition/formatting).
  • Privacy (ADR-011): local text only.
  • Caveat: heuristic "Full Name (ACR)" detection; off by default.