Medication Intelligence Engine — Full Phased Build Plan

Date: 2026-06-04 · Owner: Gene (Pharmacy Ops) · For: Gene (review) → Faraz/Emil (build) → leadership demo (Replit). What this is: the single plan that unifies every medication-input deliverable we've produced into one buildable engine — and ends in a working Replit demo that shows it end-to-end.

The thesis. The medication-input engine is the foundation of the whole product. It turns messy input (a scanned Rx list, a typed name, an import) into one clean, structured, verified, provenance-tagged medication object — and that object feeds every downstream system: scheduling, the Balance Meter, refill, and the learning loop. Build it once, build it right, and everything downstream gets easier. The audit's lesson: we have the rules; this plan adds the runtime and the build sequence.

---

1 · What we're unifying (every prior deliverable, in one place)

Deliverable	What it gives this engine	Where
Structured SIG Schema v1	the medication object model (NCPDP SCRIPT SCS + FHIR MedicationRequest.dosageInstruction), the NDC-enrichment pipeline (OpenFDA + RxNorm + DailyMed), the SIG builder, the pharmacist verification gate, multi-phase sigs (tapers), the Surescripts/Phase-2 path	Product_Specs/Structured_Sig_Schema_v1/Spec.md
Faraz med-matching guardrails (v2)	the smart-match defaults (modal product/strength/route/freq), the guardrails (confidence-gated · never-invent · high-risk force-confirm · confirm-never-prescribe), provenance-weighting	Product_Specs/Medication_Matching_Guardrails_for_Faraz_2026-06-02
Med-Input Engine audit + explainer	the runtime layer — the pipeline, the med-object contract, rules-as-config, the confidence model, the decision tree, the downstream interfaces	Product_Specs/Medication_Input_Engine_AUDIT_2026-06-04 + …_Explainer_2026-06-04.html
AI-Learning Strategy & Spec	the learning loop (corrections → better defaults) + the safety rail (learn → validate → clinical sign-off → gated deploy)	Product_Specs/AI_Learning_Strategy_and_Spec_2026-06-03
Smart Scheduling (KB 01–05, brief, claim-arch, AI architecture)	the #1 downstream consumer — cadence/tolerance from the structured SIG + the curated drug-forgiveness KB; the RAG-over-KB + safety-rail architecture pattern	Smart_Scheduling/
Balance Meter	another downstream consumer — FRID / Beers / ACB med-risk scoring from the med object	Fall_Risk/
Onboarding ≤15-min budget	the time target + the scan-the-Rx-summary intake lever	Product_Specs/Onboarding_Time_Budget_15min_2026-06-03
NCPDP SCRIPT SCS reference	the standard the object aligns to (forward-compatible to Surescripts)	11_Reference/NCPDP_SCS_extracted_spec.md
Prior-filing digest	IP coherence — OCR scan, smart-match, duplicate/interaction flags are disclosed in our provisional ([0072],[0088],[0092],[0156]); building this implements held IP	Smart_Scheduling/_Prior_Filing/
Anchor-site fills (188,953)	seed the modal-priors (which strength/form/freq is actually most common)	08_Data_DeIdentified/ (local, de-identified)

One-line read: the SIG Schema gives the object, the guardrails give the rules, the audit gives the runtime, the AI-learning spec gives the loop, and Scheduling + Balance Meter are the consumers. This plan sequences them.

---

2 · The end state (the north star — and what the demo proves)

A pharmacist (or a senior, or an import) puts a med list in any way → the engine produces one structured medication object per drug → the member confirms in seconds → and the same object instantly powers a reminder schedule (cadence + tolerance), a fall-risk read (FRID/Beers), a refill forecast, and gets smarter with every correction. The Replit demo (Phase 5) shows exactly this loop, end-to-end, on sample data.

---

3 · The phases

Phase 0 — Foundations: the contract + the data (build these first — nothing works without them)

Goal: the spine everything else plugs into. - The medication-object contract — one normalized object (NCPDP SCS + FHIR MedicationRequest.dosageInstruction + provenance/confidence/flags extensions). (Concrete sketch in §6.) - Drug-identity layer — RxNorm/RxNav (RXCUI + RxClass for class mapping) · OpenFDA NDC Directory (NDC/strength/form/route/DEA) · DailyMed SPL (sig + food rules, v2). - Modal-priors table — seeded from the 188,953 anchor-site fills + public utilization; the "most-common strength/form/freq" data. - Ruleset-as-config — the high-risk list (Beers FRIDs · NTI · controlled · LASA), the confidence thresholds, the flag rules — versioned, pharmacist-curated (not hard-coded). - Event schema + de-ID boundary — the medication-input event taxonomy; PHI stays operational/on-device, learning data de-identified at the boundary. - Draws on: SIG Schema §5–6 (object model + enrichment), audit §2 (the contract + config), KB04 (curated-KB pattern). - Deliverables: the schema doc (§6) · identity adapters · priors seed · the config · the event taxonomy. · Owner: Faraz + Emil (Gene/Dr. B curate the high-risk list + priors).

Phase 1 — The deterministic engine: scan → structured object → confirm (the pilot)

Goal: a working intake that hits the ≤15-min onboarding target with no ML yet. - Scan the printed Rx summary → OCR parse rows (3D-rotation OCR + object detection + text recognition + contextual extraction, per [0072]). - Identity enrichment — resolve NDC / name → RXCUI + form/route/strength. - Structured SIG builder — the smart defaults (modal), multi-phase for tapers, the live SigText preview. - The confidence gate — the decision tree: auto-default (high conf + not high-risk) · force-confirm (high-risk) · manual (low conf / no match; never invent). - Pharmacist verification gate — NPI-signed, timestamped → provenance tag. - During-entry smart flags — duplicate/wrong-med · interaction-separation · fall-risk-class → pharmacist view only (⚖). - Draws on: SIG Schema (the whole Step-4 flow + verification gate), Faraz guardrails (defaults + guardrails), audit (decision tree). - Deliverables: the scan→confirm flow (pilot-ready) · the SIG-builder UI. · Owner: Faraz (eng) + Jack (design) + Gene/Dr. B (clinical rules).

Phase 2 — Downstream integration: one object, many engines

Goal: the confirmed object actually powers the rest of the product. - Emit the med-object to: Scheduling (cadence + tolerance from the structured SIG × the drug-forgiveness KB) · Balance Meter (FRID/Beers/ACB med-risk) · Refill (anticipation + pattern). - The cross-engine "medication-change" event — a new fall-risk med start fires one event that tightens the Balance Meter watch-window and opens a scheduling-attention period (our patent delta). - Draws on: Smart Scheduling (cadence/tolerance, drug-forgiveness KB), Balance Meter (med-risk), the claim-architecture (the cross-engine event). - Deliverables: the downstream emitters + their contracts · the med-change event bus. · Owner: Faraz + the scheduling/Balance-Meter owners.

Phase 3 — Intelligence + learning: it gets smarter

Goal: every correction improves the next match — safely. - Matching learning loop — corrections refine the modal priors (per drug, per population/age band). - OCR/parse learning loop — misreads train the label parser. - The safety rail + pharmacist gate — a promoted default (esp. high-risk) passes clinical sign-off before it changes behavior (the AI-learning spec's gate). - Metrics instrumentation — time-to-enter (per med + per list) · auto-fill acceptance · edit/correction rate (so we don't reward rubber-stamping) · scan-parse accuracy · high-risk-forced-confirm rate · match precision/recall. - Draws on: AI-Learning spec (loops + safety rail), audit §5/§7 (governance + metrics), KB04 (metrics discipline). - Deliverables: the learning loop + the metrics dashboard. · Owner: tech + Matilda/Dr. B (validation gate).

Phase 4 — Standards / scale-up: the Surescripts path

Goal: ingest structured prescriptions directly; ready the enterprise/CVS pitch. - NCPDP SCRIPT ingest — incoming structured messages (SCS, v2021011 → v2023011) map into the same medication object (no rewrite — that's why we built structured now). - The enterprise demo path — structured data the CVS/enterprise pitch requires. - Draws on: SIG Schema (the SCS alignment + Surescripts strategy), NCPDP references. - Deliverables: the SCRIPT mapping layer. · Owner: Faraz + Emil + counsel (certification).

Phase 5 — The Replit demo: prove it end-to-end (the "at the end" Gene asked for)

Goal: a clickable web app that shows the whole loop on sample data — for leadership + the enterprise pitch. (Full spec in §5.)

---

4 · Sequencing, critical path & owners

Phase	Depends on	Owner	Gate
0 Foundations	—	Faraz/Emil + Gene/Dr. B (curate)	the med-object contract signed off
1 Deterministic engine	0	Faraz + Jack + Dr. B	pilot-ready; verification gate works
2 Downstream	0,1	Faraz + scheduling/BM owners	the cross-engine event fires
3 Learning	1,2 + de-ID boundary	tech + Matilda gate	pharmacist-gate on promoted defaults
4 Surescripts	0 (object), 1	Faraz/Emil + counsel	SCRIPT maps to the same object
5 Replit demo	0,1 (+ mock 2)	Gene + Faraz	end-to-end on sample data

Critical path: the medication-object contract (Phase 0) gates everything — it's the one artifact to nail first. Build-order rule: normalize before you match · contract before you integrate · config before you code-in · pharmacist-gate before you auto-promote. The Replit demo (Phase 5) can run on Phase-0/1 + mocked Phase-2, so it doesn't wait for the full build.

---

5 · The Replit demo spec (Phase 5)

What it proves in 90 seconds: messy input → a clean structured object in seconds → and that one object instantly drives a reminder schedule + a fall-risk read + a refill forecast, getting smarter as you correct it.

The demo flow (single web page, staged): 1. Input — paste a sample Rx-list text (or pick a sample "scanned" list); a few realistic rows (metformin, lisinopril, atorvastatin, warfarin, a combo, a PRN inhaler). 2. Normalize + enrich — live calls to RxNorm + OpenFDA (free, no key needed) resolve each → RXCUI + form/route/strength + class. 3. Smart-match — the modal-priors (a small seeded table) fill strength/freq; show the filled default + "not this?". 4. The confidence gate — visibly route each row: ✅ auto-default · ⚠ warfarin → force-confirm · ✋ a deliberately-ambiguous one → manual. 5. Smart flags — show a duplicate/interaction flag in the "pharmacist view." 6. Confirm — one tap; the structured medication object appears (the JSON/FHIR). 7. Downstream (the wow) — from that one object, the page generates: a reminder schedule (cadence + tolerance) · a fall-risk chip (FRID/Beers) · a refill date. "One object, four engines." 8. Learning — correct a default → watch the prior update for next time.

How to build it in Replit (scope it tight): - Stack: Python Flask (or Node/Express) + a single HTML page (reuse the explainer's burgundy style). Replit hosts it instantly with a shareable URL. - Live data: RxNorm/RxNav + OpenFDA NDC — free public APIs, no key — so the enrichment is real, not faked. - Mocked (for the demo): OCR (paste text instead of an image) · the modal-priors table (a small JSON seed) · the ruleset-config (a small JSON: high-risk list + thresholds) · the downstream engines (simple functions that read the object → schedule/score/refill). - No PHI, sample data only, read-only. Public APIs + synthetic patients. Honors the data rules. - Deliverable: a shareable Replit URL + the repo, ready to screen-share for leadership and drop into the enterprise pitch.

Why Replit: zero-setup hosting + a shareable link + live API calls — perfect for a demo that has to look real without a backend deploy. (The production build is Faraz/Emil's stack, Phase 0–4; the Replit app is the proof + pitch artifact, not the product.)

---

6 · The medication-object contract (Phase 0's key artifact — concrete sketch)

The one object every input path produces and every downstream engine consumes. Aligns to NCPDP SCRIPT SCS + FHIR MedicationRequest.dosageInstruction, with our extensions.

{
  "medicationId": "uuid",
  "identity": {
    "rxcui": "860975",                 // RxNorm canonical
    "ingredient": "metformin",
    "brand": null,
    "ndc": "00093-1048-01",            // if known (OpenFDA)
    "doseForm": "oral tablet",         // RxNorm/OpenFDA
    "route": "oral",
    "strength": { "value": 500, "unit": "mg" },
    "drugClasses": ["biguanides"],     // RxClass (for duplicate/interaction/FRID)
    "deaSchedule": null
  },
  "sig": {                              // structured + codified (NCPDP SCS) — multi-phase for tapers
    "phases": [
      { "doseQty": 1, "doseUnit": "tablet", "route": "oral",
        "frequency": { "code": "BID", "timesPerDay": 2 },
        "timing": ["morning","evening"], "food": "with food",
        "sigText": "Take 1 tablet by mouth twice daily with food" }
    ]
  },
  "provenance": { "source": "pharmacist-verified", "weight": 1.0,
                  "npi": "…", "verifiedAt": "…" },   // self ×0.5 → scanned → verified ×1.0
  "confidence": { "score": 0.97, "gate": "auto-default" }, // auto | force-confirm | manual
  "flags": [ { "type": "fall-risk-class", "view": "pharmacist" } ], // duplicate | interaction | fall-risk
  "audit": { "ocrOriginal": "…", "confirmed": "…" }     // for the learning loop
}

Every downstream engine reads this: Scheduling uses sig + drugClasses (→ cadence/tolerance) · Balance Meter uses drugClasses + deaSchedule (→ FRID/Beers) · Refill uses sig + fill data · Learning uses audit. This is the #1 thing to lock first.

---

7 · Metrics (one set, instrumented from Phase 1)

Time-to-enter (per med + per list, vs ~8–10 fields manual) · auto-fill acceptance · edit/correction rate (the honesty check) · scan-parse accuracy · high-risk-forced-confirm rate · match precision/recall · (downstream) schedule-generation rate · de-ID-clean rate.

8 · Open decisions for Gene / the room

1. Demo scope — the 90-sec flow above, or narrower (just scan→object→schedule)?
2. Build owner split — engine (Faraz) vs scanner/OCR (Zaza) vs design (Jack); who owns Phase 0 contract?
3. The ⚖ lines (dose/freq pre-fill · during-entry flags · auto-promoted defaults) — counsel pass before or after the Replit demo?
4. Priors data — confirm the anchor-site fills + which public utilization set seeds the modal defaults.
5. Phase order — ship Phase 1 (pilot intake) first, then build the Replit demo in parallel off Phase 0/1? (rec: yes.)

---

9 · Bottom line

We're not starting from scratch — we have the object (SIG Schema), the rules (guardrails), the runtime (audit/explainer), the loop (AI-learning), and the consumers (scheduling + Balance Meter). Phase 0 locks the medication-object contract; Phases 1–4 build the engine; Phase 5 is the Replit demo that proves it. One engine, one object, every downstream system — that's the foundation and the moat.