Medication-Matching Guardrails & Smart Rules — for Faraz¶

Date: 2026-06-04 (v2) · From: Gene (Pharmacy Ops) · For: Faraz + the med-entry / scanner team Goal in one line: make adding a medication take seconds — the user identifies the drug (or scans the printed Rx summary for the whole list at once), the system pre-fills the rest (form · route · strength · frequency) from the most common real-world pattern, and the user just confirms.

Posture (per Elliot): build the smartest, fastest version — better than any competitor's intake — and let counsel draw the line on what's "too clinical." Items that touch that line are marked ⚖ LEGAL-REVIEW below; we build the ambitious version and flag, we don't pre-neuter.

v2 note (2026-06-04): refreshed to lead with scan-the-printed-Rx-summary (the pilot's #1 onboarding lever) and to note prior-filing coherence — our own June-2025 provisional already discloses the OCR scan, the smart-match, and the during-entry duplicate/interaction flags (Smart_Scheduling/_Prior_Filing/ digest, [0072],[0088],[0092],[0156]). This spec implements held IP — it keeps the wellness-lane + provenance model coherent with the patent.

1 · Why this exists¶

Manual med entry is the single biggest time sink in onboarding (Elliot assumed ~1 hr; target is ≤ 15 min total). A typical senior has ~7 meds; entering each one by hand is 8–10 fields (name, form, strength, route, frequency, times…). If the system pre-fills the obvious defaults, each med drops to identify + confirm (~2 taps). That's the win.

2 · Principles¶

Default, don't interrogate. Pre-fill the most likely formulation; the user edits only the exceptions.
One matching engine, every entry path — typed, printed-Rx-summary scan (the whole list at once — the pilot's #1 lever), bottle/label scan, Blue-Button / Part-D import, and pharmacist entry all flow through the same normalizer.
Confirm, never prescribe. The pre-fill is a data-entry convenience, not advice. We never tell the user what to take or how. (Member-facing copy stays wellness-lane / lexicon-clean.)
Provenance-weighted. self-typed < scanned/imported < pharmacist-verified — same provenance model as the Balance Meter (self-report ×0.5 → pharmacist ×1.0). Every captured med carries its tag.
Never invent. If there's no confident source match, fall back to manual — never guess a strength or dose.
Never substitute a look-alike (LASA). A real-but-unseeded drug routes to manual; a fuzzy match is a confirm-required suggestion, never an auto-swap. felodipine ≠ amlodipine. (See §5.)

2.5 · The intake flow (scan-first)¶

The fastest path isn't typing — it's scanning the whole list once:

Pilot (now): the pharmacist scans the printed Rx summary → OCR parse (3D-rotation OCR + object detection + text recognition + contextual extraction) → the matching engine fills form/route/strength/frequency for every line → the pharmacist confirms (gold provenance). The slow step lives on the pharmacist's clock, not the senior's.
Near-term: a pharmacy-software API auto-loads the list — same normalizer, no scan, no keying.
Per-med fallbacks: typed autocomplete · bottle/label scan · Blue-Button / Part-D import — all into the same engine.

(Ties to Onboarding_Time_Budget_15min + the medication-data roadmap, deck S12/S17. The OCR-scan + smart-match path is disclosed in our provisional, [0072],[0156] — building it is implementing held IP.)

3 · Sources of truth¶

RxNorm — normalized drug concepts; ingredient ↔ SCD/SBD, brand ↔ generic, combination → components, dose-form & route attributes.
OpenFDA (NDC + label) — marketed dosage forms, routes, and strengths; how a real product is labeled.
Dispensing-frequency priors — which strength/form/frequency is actually most common per drug (so the default is the modal real-world choice, not the first or lowest one). Seed from public utilization data; refine from our own corrections (the learning loop, §7).

4 · The smart-match rules (the defaults)¶

Step	Rule	Example
Ingredient → product	type a name → default to the most-dispensed product	"metformin" → metformin 500 mg oral tablet
Strength	default = the modal dispensed strength, not lowest/first	lisinopril → 10 mg
Route	default = the dominant labeled route	oral for most; flag where route disambiguates (inhaled, injectable, topical)
Frequency / SIG	default = the most common regimen for that drug, shown as an editable SIG (never an instruction)	metformin → "twice daily" · lisinopril → "once daily"
Form disambiguation	when a name maps to several forms, show the top 1–2 by frequency, not the full list	metoprolol → ER vs IR (top two only)
Brand ↔ generic	normalize via RxNorm; show generic by default, brand in parentheses	"Glucophage" → metformin (Glucophage)
Combination products	expand to components for the risk engine; display as the combo	lisinopril/HCTZ → shows combo, scores both

UX: show the filled default + a single "not this?" affordance that opens the top alternatives. The happy path is one tap to accept.

5 · Guardrails (the boundaries)¶

⚖ LEGAL-REVIEW — pre-filling dose/frequency. Defaulting a product is clearly data entry; defaulting a dose & frequency edges toward an implied recommendation. We build it (huge time-saver) and flag the line for counsel. Member-facing framing: "most people take it as…" / editable field — not "take X."
High-risk / high-ambiguity → force an explicit confirm. Don't silently auto-commit where a wrong default is dangerous: insulins, opioids, anticoagulants (warfarin), controlled substances, narrow-therapeutic-index drugs, weight-based/pediatric dosing, and look-alike/sound-alike pairs. Still pre-fill — but require a confirm tap and surface alternatives. ⚖ how far the auto-default goes on these is a counsel call.
Confidence-gated auto-fill. Commit a default only above a match-confidence threshold; below it, suggest top candidates without committing.
Never invent a strength/dose — no confident source match → manual entry.
Never substitute a look-alike (LASA). This is the partner of "never invent," and the single most important safety behavior: a drug that resolves as real (RxNorm recognizes it) but is not in our local table routes to manual entry — never to the nearest similar-spelling seeded drug. A fuzzy match is a suggestion that requires an explicit confirm ("did you mean…?"), never a silent auto-accept. Worked example: a member types felodipine; the engine recognizes it as a real medication but doesn't have it seeded, so it routes to manual — it does not quietly substitute amlodipine (the look-alike). Demonstrated live in the demo; fuzzy cutoff tuned so genuine typos (metformn → metformin) still suggest, but look-alikes do not swap.
Everything is editable + audited — capture original-vs-confirmed for the learning loop (§7).
Provenance tag on every med — feeds the Balance Meter medication engine and the pharmacist-verification gate.

6 · ⚖ Where this touches the clinical line (for counsel — Elliot's "let the lawyers decide")¶

Build the ambitious version of each; counsel sets the limit: 1. Pre-filled dose & frequency (convenience vs implied recommendation) — §5. 2. Smart flags surfaced during entry — the "smart intelligence" layer. Specifically: duplicate-therapy / wrong-medication ("you already have a drug in this class"), interaction hints + time-separation ("these two are usually spaced apart"), and fall-risk-class awareness. Hugely valuable and faster, but CDS-adjacent. (All three are disclosed in our provisional — duplicate/wrong-med [0092], interaction time-separation [0088] — so they're grounded, and counsel should carry them into the non-provisional.) Proposal: compute always; show in the pharmacist view; member-facing only as wellness-safe nudges, if at all. Flag. 3. Auto-default behavior on high-risk drugs — §5.

We design all three to the smartest spec and mark them for the legal pass, rather than shipping a timid version.

7 · The learning loop (handoff to the AI-learning spec)¶

Every interaction makes the next match better: - User swaps a default → updates the per-drug priors (which strength/form/freq to default next time — globally and per population/age band). - Scan misread corrected → trains the OCR/label-parse. - Pharmacist correction → highest-trust signal; promotes a default.

This is the seam to the AI-learning spec (separate deliverable) — what the product's AI learns, from which signals, with what guardrails.

8 · Success metric¶

Time-to-enter a med: target identify + 1-tap confirm (≈ 2 interactions) vs ~8–10 fields manual.
A 7-med list: target < ~3 min end-to-end (scan/import pre-populates; matching fills the gaps), inside the ≤ 15-min onboarding budget.
Auto-fill acceptance rate (how often the default is accepted unedited) — the north-star quality metric; rises as the learning loop runs.

9 · Open questions (flagged per Gene's "ask, don't guess")¶

Entry-path priority — I scoped this as one engine for all paths (typed/scan/import/pharmacist) with member self-entry speed as the headline. Confirm that's right, or focus it on one path first.
Counsel items (§5–6) — who runs the legal pass, and how aggressive do we go on auto-defaulting dose/frequency + the during-entry smart flags?
Current baseline — what does med entry take today (per med / per list)? Needed to set the real target numbers.
Build owners — the OpenFDA+RxNorm autocomplete is already with tech; does this spec sit with that workstream or the scanner (Faraz/Zaza) workstream, or both?