# ED Encounters — Application Logic > Multi-stage emergency department documentation with per-stage AI generation, > "don't miss" tooltips per stage, and a final consolidate→MDM pipeline at > Save & Done. Lives in its own tab between **Dictation HPI** and the > **Notes** sidebar group. This is the deepest, freshest doc in the `logic/` series — the feature was built and revised across one focused session in late April 2026 and most of the architectural decisions are explicitly motivated below. Read this first if you want to understand how a clinical workflow gets composed in this codebase. --- ## 1. What this is An ED encounter is structurally different from every other clinical note in the app: - A sick visit, well visit, SOAP note, or HPI is **one transcript → one generated note**. The physician records, clicks Generate, edits, saves. - An ED encounter is **multiple successive recordings → multiple successive notes → one final consolidated note + MDM**. The physician dictates the initial assessment, generates a note. Labs come back, they record more, generate again. After consult, more dictation, generate again. When done (could be after 1, 2, 3, or N stages), they click Save & Done and the server consolidates everything into one polished note plus a 2023 AMA E/M Medical Decision-Making block for billing. The user-visible model: each generated stage stays on screen as its own editable card with its own "Don't Miss" panel. The physician can edit any stage at any time. Whatever's on screen at finalize time is what gets sent to the consolidate step. Physicians can also include direct asides in their dictation ("include normal cardiac exam", "assessment is viral URI") and the AI is explicitly instructed to route those to the right note section instead of quoting them. --- ## 2. The user flow, end to end 1. **Open the tab.** Sidebar → **ED Encounter**. Tab is lazy-loaded (the `
` placeholder in `public/index.html` triggers a fetch of `public/components/ed-encounter.html` on first activation). 2. **Enter patient info.** Label (required for save), age, gender, chief complaint (required for generation), and a model dropdown (the same `class="tab-model-select"` pattern every clinical tab uses; auto-populated by `app.js` against the admin's allowed-models list). 3. **Record or type Stage 1 dictation.** Standard recorder (`AudioRecorder` from `public/js/audioBackup.js`) + browser SpeechRecognition for live transcript preview + final server STT pass on stop. Same plumbing as every other clinical tab. 4. **Click "Generate Stage 1 Note".** Frontend POSTs to `/api/ed-encounters/generate` with `{stage: 1, transcript, chiefComplaint, patientAge, patientGender, physicianMemories, model}`. Server returns `{success, note, dontMiss[], model}`. Note appears as **Stage 1** card. Don't-miss items appear as a yellow/orange section embedded in that same card. 5. **Edit if needed.** Each stage's note element is `contenteditable`. Type freely; edits persist to localStorage on each input event. 6. **Refine the latest stage** (optional). The "Refine latest" textarea + button at the bottom of the stage list calls `/api/refine` with the latest stage's text + your instruction. The latest stage's text is replaced inline with the refined version. 7. **Add another stage** (optional). Click "Add more (next stage)". Stage 1 card stays visible. Transcript box clears. Badge changes to "Stage 2 (recording)" — yellow background — meaning we've advanced but no Stage 2 note has been generated yet. 8. **Repeat** for as many stages as you need. 9. **Click "Save & Done (with MDM)"** at any point. - Server runs `edConsolidate` → produces one polished final note that integrates every stage chronologically. - Server then runs `edFinalize` → produces a 2023 E/M MDM block as JSON. - Both come back in one HTTP response. - Frontend renders a **"Final Consolidated Note"** card (blue left border) and a **"Medical Decision Making (2023 E/M)"** card (green left border) below the stage cards. - Stage cards become read-only. - The whole thing persists to `saved_encounters` with `status='final'`. - Local draft cleared. --- ## 3. State model Lives in a closure variable in `public/js/ed-encounters.js`: ```js _state = { stage: 1, // current stage number (what the recorder is for) stages: [ // per-stage history — one entry per generated stage { transcript, note, dontMiss[], model, generatedAt } ], finalized: false, finalNote: null, // consolidated final note from /finalize mdm: null // 2023 E/M MDM block from /finalize } ``` ### Invariants - `_state.stage` increments monotonically. It only goes up via the user clicking "Add more". It is the **target** stage of the recorder/generate button. - `_state.stages.length` is the number of stages **already generated**. The array is indexed 0..N-1; stage 1 is at index 0, stage 2 at index 1, etc. - The relationship `_state.stages.length === _state.stage` means "the current stage has been generated, ready to finalize or advance." - The relationship `_state.stages.length === _state.stage - 1` means "we're recording into a new stage that hasn't been generated yet" (the yellow `Stage N (recording)` badge state). - `_state.finalized` flips to `true` only when finalize succeeds. Once true, Add more / Generate / Refine all reject with a toast. ### Why this shape Earlier iterations stored a single `currentNote` string and rotated stages out of view on each generation. Daniel's clarification was explicit: every stage's note must remain visible and editable; the final MDM should reflect whatever's on screen, including any inline physician edits to earlier stages. The `stages[]` array is the source of truth and `gatherCurrentNotes()` re-syncs it from the DOM before any operation that needs current text. --- ## 4. The badge — accurate state communication Top-right of the save bar. Exactly four states: | Condition | Text | Background | |---|---|---| | `_state.stages.length >= _state.stage` (current stage has been generated) | `Stage N` | Gray | | `_state.stages.length < _state.stage` (advanced past last generation; no note for stage N yet) | `Stage N (recording)` | Yellow | | `_state.finalized && !_state.mdm` (transient) | (not reached — finalize is atomic) | — | | `_state.finalized` | `Finalized` | Green | This badge was the source of the most confusing UX bug in v1: clicking "Add more" used to immediately flip the badge to "Stage 2" even though no Stage 2 note existed yet. The fix isn't subtle — `updateBadge()` derives the label from the relationship between `_state.stages.length` and `_state.stage`, with explicit color coding so the difference is unmistakable. --- ## 5. Frontend file map ### `public/components/ed-encounter.html` The static markup. Roughly: - **Save bar** (`#ed-save-bar`) — label input, badge (`#ed-stage-badge`), Save draft / Load / New buttons, plus a Load popover for saved drafts. - **Patient Info card** — age (`#ed-age`), gender (`#ed-gender`), chief complaint (`#ed-cc`), and the model select (`#ed-model-select` with the `tab-model-select` class). - **Recording card** — header showing `Stage N Recording / Dictation`, the Listen In / Pause buttons, the recording indicator with timer, and a contenteditable transcript box (`#ed-transcript`). - **Generate button** (`#btn-ed-generate`) — `Generate Stage N Note`. - **`#ed-stages-container`** — empty div. JS appends one card per stage here. - **`#ed-tail-controls`** — refine bar (textarea + Refine latest + Shorter) + stage-control row (Add more, Save & Done). Hidden until at least one stage exists. Hidden again after finalize (encounter is locked). - **`#ed-mdm-card`** — the green-bordered MDM card. Hidden until finalize. The blue-bordered "Final Consolidated Note" card is **created dynamically** by `renderFinalNote()` and inserted before the MDM card. ### `public/js/ed-encounters.js` Single IIFE module. Key functions: | Function | What it does | |---|---| | `freshState()` | Returns a clean `_state` object — used at module load and `resetEncounter()` | | `gatherCurrentNotes()` | Walks the DOM stage cards (`#ed-stage-text-N` elements) and writes their current text back into `_state.stages[N].note`. Called before persist, advance, finalize, generate (the last because the AI prompt for stage N+1 needs the latest text of stage N as `previousNote`). | | `persistLocal()` | Debounced 300ms localStorage save under key `ped_ed_draft_v1`. Snapshot includes `_state` plus the current label/age/gender/CC/transcript box content. | | `loadLocal()` | Reverse of `persistLocal()` — restores state on tab open if a draft exists. | | `renderStages()` | Rebuilds `#ed-stages-container` from `_state.stages[]`. Each card gets a unique id `ed-stage-text-N`. Cards become `contenteditable=false` after finalize. | | `buildStageCard(idx, stage)` | Constructs one card's DOM. Includes the editable note + an embedded yellow "Don't Miss — Stage N" section if `stage.dontMiss` is non-empty. | | `renderFinalNote(note)` | Lazily creates `#ed-final-note-card` (blue border) and inserts it before the MDM card. | | `renderMdm(mdm)` | Fills `#ed-mdm-card` with structured MDM HTML (problems / data / risk paragraphs + suggested level + rationale + disclaimer). | | `updateBadge()` | Sets `#ed-stage-badge` text + background color based on state. | | `initRecording()` | Wires the record / pause buttons, browser SpeechRecognition, AudioRecorder, transcribe-on-stop. Identical pattern to `sickVisit.js` — copy-pasted because the recording paths are sacred and shouldn't be factored into a shared helper. | | `generateStage()` | Validates inputs, calls `gatherCurrentNotes()`, fetches user templates via `getUserMemoryContext()`, POSTs `/api/ed-encounters/generate`, pushes the result into `_state.stages[stage-1]`, re-renders, autoSaves a draft to the DB. | | `advanceStage()` | Validates current stage exists, gathers edits, increments `_state.stage`, clears the transcript box, updates the badge to "(recording)", scrolls to the recorder. **Does NOT touch any displayed cards.** | | `finalize()` | Validates label + at least one stage, gathers edits, POSTs `/api/ed-encounters/finalize` with the full stages array, on success renders Final Note + MDM cards, marks finalized, calls `saveEncounter` with `status='final'`, clears localStorage. | | `composeFinalNoteForSave(note, mdm)` | Concatenates the final note + MDM block into a single text blob written to `saved_encounters.generated_note` (so the saved encounter has a single coherent stored note for any downstream consumer). | | `autoSaveDraft()` | Best-effort — saves a `status='draft'` row to `saved_encounters` if a label is set. Called after each stage generation. Silent if no label. | | `resetEncounter()` | "New" button — wipes state, removes stage cards, hides Final Note + MDM, clears localStorage, drops the saved-encounter id. | | `refineLatestStage()` / `shortenLatestStage()` | Resolve the latest stage's text element id (`stageTextElId(stages.length - 1)`) and call the global `refineDocument` / `shortenDocument` helpers from `app.js`. | ### How the file integrates with `encounters.js` `public/js/encounters.js` is **sacred** (per the project memory file — don't refactor without per-change approval, especially the save/idempotency logic). ED encounters needed exactly two minimal touches to it: 1. Line 98: `'ed'` added to the sessionStorage restore array so the `_savedEncId_ed` value survives page refresh. 2. Lines 305-310: `ed: 'ed'` added to the `tabMap` in `resumeEncounter` so the saved-encounters list can navigate to the ED tab when a user clicks a saved ED row. That's it. Save logic, idempotency, optimistic versioning — all reused unchanged via `window.saveEncounter()`. ED rows store with `enc_type='ed'` and `partial_data` containing the full `{stages, finalNote, mdm, finalized}` JSON for resume. A `registerEncounterLoadHandler('ed', fn)` call near the bottom of `ed-encounters.js` registers the resume handler with `encounters.js`. When a user clicks an ED row in the Load popover, `encounters.js` invokes that handler with the decrypted row, and the handler restores `_state` and re-renders. --- ## 6. Backend file map ### `src/routes/edEncounters.js` Two endpoints, both auth-gated. #### `POST /api/ed-encounters/generate` Per-stage note generation. Body: | Field | Type | Notes | |---|---|---| | `stage` | number | Informational; the prompt is told this is "Stage N" | | `transcript` | string | **Required.** This stage's raw dictation. | | `chiefComplaint` | string | **Required.** Same as in other tabs. | | `patientAge` | string | Optional but strongly preferred — drives "don't miss" tailoring | | `patientGender` | string | Optional | | `previousNote` | string | Stage 2+ only. The previous stage's current text (after edits). | | `physicianMemories` | string | Concatenated user templates from `/api/memories/context` | | `model` | string | Optional override. Validated by callAI's allowlist. | Returns: ```json { "success": true, "note": "", "dontMiss": [{"point","why"}], "model": "" } ``` The route assembles a structured user message: ``` ED ENCOUNTER — STAGE N Patient: , Chief Complaint: CURRENT STAGE TRANSCRIPT (may include direct physician asides — preserve and route them per the prompt rules): PREVIOUS-STAGE NOTE (baseline to integrate on top of — do not start fresh): [only stage 2+] PHYSICIAN TEMPLATES AND PREFERENCES: [if any] ``` Calls `callAI` with `PROMPTS.edEncounterStaged + INJECTION_GUARD` as system and the assembled user message. Parses the response with `extractJson`. **Recovery logic:** if the model returns plain prose instead of JSON (model occasionally shortcuts), the route treats the entire response as the note and returns an empty don't-miss list rather than 500-ing. The physician still gets a usable note. `dontMiss` is filtered to entries with non-empty `point` and trimmed. Audit + apiCall logs are written. #### `POST /api/ed-encounters/finalize` Two-call server-side pipeline. Body: | Field | Type | Notes | |---|---|---| | `stages` | `[{transcript, note}]` | **Required.** Array in chronological order. Empty stages are filtered. | | `chiefComplaint` | string | Optional but strongly preferred | | `patientAge` | string | Optional | | `patientGender` | string | Optional | | `model` | string | Optional override | The route: 1. **Step 1 — consolidate.** Builds a context with chief complaint, demographics, and a labeled `=== STAGE N ===` block for each stage (transcript + working note). System prompt is `PROMPTS.edConsolidate`. Returns the model's plain-text response as `finalNote`. 2. **Step 2 — MDM.** Builds a context with the consolidated `finalNote` plus the full transcript across all stages. System prompt is `PROMPTS.edFinalize`. Parses JSON for `{mdm: {...}}`. Returns: ```json { "success": true, "finalNote": "", "mdm": { "problemsAddressed": "minimal|low|moderate|high", "problemsNarrative": "...", "dataReviewed": "minimal|limited|moderate|extensive", "dataNarrative": "...", "risk": "minimal|low|moderate|high", "riskNarrative": "...", "suggestedLevel": "99281|99282|99283|99284|99285", "levelRationale": "..." }, "model": "" } ``` **Why two calls instead of one combined prompt:** each task has a focused rubric (the consolidate prompt enforces section structure and chronological integration; the MDM prompt enforces the 2023 AMA element definitions). Asking for both in one JSON tends to make the model shortcut one or the other. Two calls cost ~2x latency at the very end of the encounter — acceptable since finalize is a one-time terminal action. If the MDM step's JSON parse fails, the route returns 502 but **still includes the finalNote** in the error payload so the client doesn't lose work. (The client doesn't currently surface this case to the user — TODO to render the partial result with a "MDM failed, retry" affordance.) Token usage from both calls is summed for the apiCall log. ### `src/utils/prompts.js` — the three ED prompts #### `edEncounterStaged` System prompt for per-stage generation. Returns strict JSON `{note, dontMiss[]}`. Key instructions: - Note structure is **fixed**: Chief Complaint, HPI (OLDCARTS, historian noted), ROS (per ROS_PE_RULES), PE (per ROS_PE_RULES), ED Course (only when present), Assessment and Plan. - Don't-miss list is **uncapped** for ED (unlike the global `dontMissTooltip` prompt which hard-caps at 5 for sick visit / encounter HPI). Quality over quantity. Tailored strictly to age + chief complaint. - **PRESERVE INSTRUCTIONS WITHIN DICTATION** — explicit instruction that physician asides like "include normal cardiac exam" or "assessment is viral URI" are first-class clinical input. Route exam findings to PE, assessment statements to A&P, plan statements to A&P. Never echo as quoted speech. - **Templates** — the user's templates (especially `template_ed`, but also matching `template_hpi`/`template_soap`/`template_sickvisit`) are delivered in the user message as PHYSICIAN TEMPLATES AND PREFERENCES. Apply matching template sections; never copy clinical content from a template — only formatting/structure. - **Previous-stage note** — explicit instruction: integrate the new transcript on top of the previous note, do not start fresh. Drop don't-miss items that have been addressed. The prompt is appended with `INJECTION_GUARD` from `promptSafe.js` to defend against prompt-injection attempts inside the dictation. #### `edConsolidate` System prompt for the consolidate step at finalize. **Plain text output** (no JSON wrapper). Key instructions: - Same fixed note structure as the staged prompt. - **Integration rules**: use the latest stage as the structural baseline (it already integrates earlier stages); use earlier stages and transcripts to fill gaps. ED Course should reflect chronological progression. Resolve contradictions by using the later value AND noting the change in ED Course (e.g., "now afebrile after antipyretic"). - Preserve every clinical fact; never drop information; never invent. #### `edFinalize` System prompt for the MDM step. Returns strict JSON `{mdm: {...}}`. Includes a **full inline rubric** of the 2023 AMA E/M MDM table so the model has clear definitions to score against: - **Element 1 — Problems addressed**: minimal / low / moderate / high with explicit definitions (e.g., "high = chronic illness with severe exacerbation, OR acute illness/injury that poses threat to life or bodily function"). - **Element 2 — Data reviewed**: categories (tests reviewed, tests ordered, independent interpretation, discussion with another physician, external records, independent historian) and counting rules for minimal / limited / moderate / extensive. - **Element 3 — Risk**: minimal / low / moderate / high with concrete examples per level (drug therapy requiring intensive monitoring, decision regarding hospitalization, etc.). - **Level mapping** (2 of 3 elements must meet the level): 99281 through 99285 with descriptions of the typical encounter at each level (99284 = "MODERATE complexity MDM, most common ED visit with workup, labs, or imaging and prescription decisions"; 99285 = "HIGH complexity MDM, admission for high-acuity care"). Critical rules at the bottom: - Use only information present in the note (and transcript if provided). - Never invent. - Conservative when ambiguous — pick the lower level. - `levelRationale` must reference specific elements actually documented. This prompt is the most important to get right — it's what determines the suggested billing level. Daniel called this out explicitly: "make sure mdm is configured well." The full element rubric is inline so the model isn't relying on its training to remember the 2023 guidelines correctly. --- ## 7. Persistence — three layers ### Layer 1 — localStorage (`ped_ed_draft_v1`) Debounced 300ms after every input event. Snapshot includes the entire `_state` plus the current label / age / gender / CC / transcript box content. Survives page refresh, browser restart, signing out + back in. Cleared on `resetEncounter()` and on successful finalize. This is the **fast** layer — captures every keystroke without round-trips. ### Layer 2 — saved_encounters DB row, status='draft' Best-effort auto-save after each stage generation. Requires a label to be set; silent no-op otherwise. Uses `window.saveEncounter` from `encounters.js` with: - `enc_type: 'ed'` - `status: 'draft'` - `generated_note`: the latest stage's note (so the saved-encounters list has something to preview) - `partial_data`: encrypted JSON containing `{stages, finalized: false}` - `idempotency_key: 'ed-draft-' + savedId` The same row gets updated on each subsequent generation (by passing the saved id back to `saveEncounter`). This is the **durable** layer — survives device loss because it's on the server, encrypted at rest with the app key. ### Layer 3 — saved_encounters DB row, status='final' Written exactly once on successful finalize. Includes: - `generated_note`: the **final consolidated note + MDM block** combined via `composeFinalNoteForSave()`, so any downstream consumer (export, copy, print) gets a single coherent text. - `partial_data`: `{stages, finalNote, mdm, finalized: true}` — full fidelity for resume / audit / future re-render. - `idempotency_key: 'ed-final-' + Date.now()` — unique per finalize attempt so a network retry doesn't create a duplicate row. After finalize, localStorage is cleared. The encounter is locked from further edits in-app (stage cards become `contenteditable=false`, tail controls hidden). The user can still load the row later for review; editing requires loading then unlocking by some manual workflow that doesn't yet exist (TODO if requested). --- ## 8. The "Don't Miss" tooltip — per-stage Each stage's response from `/api/ed-encounters/generate` includes a `dontMiss[]` array of `{point, why}` objects. Same JSON call as the note — no second AI request. The stage card embeds these as a yellow/orange section beneath the note text: ``` ┌─────────────────────────────────────────┐ │ Stage 2 Note [model] [Copy] │ ├─────────────────────────────────────────┤ │ Chief Complaint: ... │ │ HPI: ... │ │ ... │ ├─────────────────────────────────────────┤ ← yellow background │ ⚠ Don't Miss — Stage 2 │ │ • Document hydration status │ │ (tachycardia + 4-day vomiting) │ │ • Consider DKA workup │ │ (polyuria + weight loss in HPI) │ │ • ... │ └─────────────────────────────────────────┘ ``` ED don't-miss is **uncapped** by design — Daniel wanted no limit ("just like remember to ask this, do this, keep this in mind etc."). Compare with `/api/dont-miss` (used by sick visit + encounter HPI) which caps at 5 both in the prompt and via server-side `.slice(0, 5)`. The same-call design (note + don't-miss in one JSON) was a deliberate choice to keep per-stage latency down. The risk (model occasionally shortcuts the don't-miss list) is acceptable per Daniel since don't-miss is informational, not load-bearing. --- ## 9. Templates — `template_ed` When a physician saves a template under category `template_ed` (Settings → Templates), it gets included in the `physicianMemories` string that the frontend fetches via `getUserMemoryContext()` and passes to `/api/ed-encounters/generate`. The flow: 1. User saves a template named e.g. "ED Pearls" with category `template_ed`. 2. Server stores it in `user_memories` (encrypted name + content). 3. On next ED note generation, `ed-encounters.js` calls `getUserMemoryContext()` (defined in `public/js/memories.js`). 4. That function fetches `/api/memories/context` which returns a single string containing every active template (correction_* rows are filtered out at the SQL level — the AI corrections feature was removed in late April 2026). 5. The string is included in the user message under the "PHYSICIAN TEMPLATES AND PREFERENCES" header. 6. The system prompt's "PHYSICIAN TEMPLATES" section instructs the model to apply matching sections from any template (especially `template_ed`, but also matching HPI/SOAP/sickvisit templates). `template_ed` was added to `VALID_CATEGORIES` in `src/routes/memories.js` and to the dropdown in `public/components/settings.html`. --- ## 10. Why the design looks like this Each major decision, with the constraint that motivated it. ### Why per-stage cards (vs. one rolling note element) **Daniel's clarification.** The first build used one `#ed-note-text` element that got replaced on each generation. After demo: "every stage note should be shown, if AI is told to modify that particular note then the modified version is used in final mdm." The cards model is the direct response — every stage stays visible, every stage is editable, edits flow into finalize. ### Why the badge has an explicit "(recording)" state **Bug from first user test.** Clicking "Add more" used to flip the badge to "Stage 2" immediately, before any Stage 2 note existed. Daniel: "the title changes to stage 2 even without a new recording and generate being hit." The fix isn't subtle — `updateBadge()` derives state from the relationship between `stages.length` and `_state.stage`, with explicit color coding so the difference is unmistakable. ### Why finalize is two server-side AI calls instead of one **Quality concern.** A single combined "produce finalNote AND mdm in one JSON" prompt makes the model cut corners on one of the two tasks (usually the MDM rubric gets compressed). Two focused calls each get their own dedicated system prompt with no competing pressure. Cost: ~2x latency at finalize. Justification: finalize is a one-time terminal action, not a per-stage hot path. ### Why edConsolidate returns plain text instead of JSON **Reliability + simplicity.** The consolidate step produces ONE thing — a clinical note. JSON wrapping adds parse-failure surface area for zero benefit. The text is rendered directly into a `contenteditable` element. The MDM step does need JSON because it has structured fields the UI displays in a table layout. ### Why the MDM prompt has the full 2023 AMA rubric inline **Daniel's directive: "make sure mdm is configured well."** Models' training data includes pre-2023 guidelines mixed with 2023; relying on "you know the AMA E/M MDM table" produces drift. The prompt now includes element-by-element definitions (problems / data / risk), counting rules for data, and concrete examples per level. The level rationale must reference specific findings. ### Why the recorder code is copy-pasted from sickVisit.js **Project memory: "Voice/STT is sacred — Don't refactor recorder/transcribe plumbing; fix only named bugs in smallest diff."** The recording paths in every clinical tab look almost identical; refactoring to a shared helper is a textbook clean-code move that has burned this project before (silent breakage of recording when the abstraction ate an edge case). The deliberate non-DRY duplication is the safer choice. ### Why finalize sends the whole stages array instead of just stage texts The consolidate prompt benefits from seeing each stage's transcript (physician's actual dictation) AND each stage's note (which may include physician edits). The transcripts let the AI catch facts that didn't make it into the working notes; the notes show physician interpretation. Both together produce a more faithful consolidation. ### Why `previousNote` is sent during stage 2+ generation, not just the transcript The per-stage AI is told to "integrate the new transcript on top of the previous note as baseline, do not start fresh." Without the previous note as input, stage 2 would have to regenerate everything from transcripts alone (slower, less faithful to physician edits made between stages). --- ## 11. Sacred / fragile zones These are not refactor-without-permission lines. ### `public/js/encounters.js` Per project memory: don't touch without per-change approval; even pre-approved changes get rejected if they refactor save/idempotency. The ED feature touched it in exactly two places (sessionStorage array and tabMap) and that's it. **All ED save/load goes through `window.saveEncounter` and `registerEncounterLoadHandler` — established interfaces. Do not add new methods to encounters.js or modify the save body shape.** ### Recorder + transcribe paths `public/js/audioBackup.js` (the AudioRecorder class), the `transcribeAudio` global function, the SpeechRecognition wrapper from `public/js/speechRecognition.js`. The ED tab's recording logic in `initRecording()` was copied from `sickVisit.js` deliberately. Don't factor it out into a shared `record-and-transcribe-helper.js`. ### The MDM prompt rubric The 2023 AMA E/M element definitions and level mapping in `PROMPTS.edFinalize` are load-bearing for billing accuracy. Don't trim them to "save tokens" — the cost of a miscoded encounter to a real practice is much higher than the prompt overhead. Update only with explicit billing/coding source citation. --- ## 12. How to extend — concrete recipes ### Add a new prompt key 1. Add the entry to `PROMPTS` in `src/utils/prompts.js`. Use the same `${CORE_RULES}` and (if relevant) `${ROS_PE_RULES}` preambles other prompts use. 2. The DB-override system (`loadFromDb` in the same file) auto-picks up the new key on next startup, so admins can override it from the Admin → Prompts UI without code changes. ### Tweak the MDM rubric Edit `PROMPTS.edFinalize` in `src/utils/prompts.js`. Cite the source (2023 AMA E/M Office or Other Outpatient guideline updates, or AMA errata) in the commit message. The rubric structure is stable — changes are usually wording refinements, not category rewrites. ### Add a new field to the stage card (e.g., timestamp) 1. The data is already in `_state.stages[i].generatedAt`. 2. In `buildStageCard(idx, stage)` in `public/js/ed-encounters.js`, add a small `
` next to the model tag in the card header. 3. No backend change needed; `generatedAt` is already saved in `partial_data`. ### Add per-stage refine (instead of "refine latest") 1. In `buildStageCard()`, render a refine input + button for every stage card. 2. Update the refine button click handler to read `data-stage-idx` from the clicked button and pass `stageTextElId(idx)` to `refineDocument`. 3. Be aware: physicians editing earlier stages then refining them then regenerating later stages creates a complex causality chain. Daniel's current call is "refine targets the latest stage" to avoid this. ### Add a new ED-specific output (e.g., a discharge instructions card) 1. Decide if it's per-stage or once-per-encounter. Per-encounter is simpler — generate it on finalize. 2. Add a third server-side AI call in `/api/ed-encounters/finalize` between consolidate and MDM. Add the result to the response payload. 3. Add a new card to `ed-encounter.html` (or create dynamically like `renderFinalNote`). 4. Render it in the finalize success handler. ### Unlock a finalized encounter for editing (TODO — not implemented) Currently no UI for this. Would require: 1. A new endpoint `POST /api/ed-encounters/:id/unlock` that flips `status` from `'final'` back to `'draft'` and clears `partial_data.finalized`. 2. An "Unlock for editing" button on the load popover for finalized rows. 3. UI logic in `ed-encounters.js` to handle the unlocked state (re-enable editing on stage cards, re-show tail controls). ### Add a fourth stage type (currently the prompt is generic) The current design treats all stages identically — same prompt, same structure. If there's a value in distinguishing "initial assessment" vs "post-workup" vs "post-consult" stages with different prompts, that's a meaningful shift. Probable plan: 1. Add a `stageType` field to each stage entry. 2. Branch on `stageType` in the route to pick a prompt variant. 3. UI: dropdown next to the recorder that defaults to "Initial / Workup / Consult / Disposition" based on stage number. This isn't currently planned — the generic stage works because the physician's dictation is what differentiates stages, not a metadata tag. --- ## 13. Testing pointers There are currently **no Playwright e2e tests** for ED encounters — flagged as TODO in the session that built the feature. A reasonable first batch: 1. **Stage 1 happy path.** Open tab, fill label/age/gender/CC, type transcript, click Generate, assert Stage 1 card appears with note text and don't-miss section. 2. **Multi-stage flow.** Stage 1 → Add more → badge says "Stage 2 (recording)" with yellow background → type Stage 2 transcript → Generate → both Stage 1 and Stage 2 cards visible. 3. **Edit-then-finalize.** Generate Stage 1 → edit the note text inline → Save & Done → assert the consolidate step received the edited text (mock `/api/ed-encounters/finalize`, inspect the request body). 4. **Finalize renders both cards.** Mock `/finalize` to return `{finalNote, mdm}` → assert blue Final Note card AND green MDM card appear → assert stage cards become read-only. 5. **Resume from saved.** Save a draft, reload, click Load, pick the ED row → all stages reappear with their don't-miss sections. The mocking pattern is in `e2e/fixtures.js` — `mockAI(page, overrides)`. Add `'**/api/ed-encounters/generate'` and `'**/api/ed-encounters/finalize'` to the routes table with canned responses. --- ## 14. Known issues / TODOs - No e2e coverage (above). - No "unlock" UI for finalized encounters. - The MDM-step partial-success case (consolidate succeeded, MDM failed) returns 502 with `finalNote` in the error payload, but the client doesn't render the partial result. Currently the user sees a generic error toast and loses the consolidate work. - Per-stage refine isn't supported — only "refine latest." If the user wants to refine an earlier stage, they edit it inline (works) but don't get an AI-assisted refine for that specific stage. - The "(recording)" badge color (yellow) might be confusing in the dark theme if one is added — currently the app is light-only. - The consolidate step uses the configured default model unless the user picks a specific one in the dropdown. There's no way to use one model for per-stage generation and a different model for finalize. Probably fine; flag if a user wants this. - `extractJson` is defined locally in `src/routes/edEncounters.js` and duplicated from `notes.js`. Candidate for `src/utils/jsonRecover.js` if a third route ever needs it. --- ## 15. Quick reference — the ED encounter at a glance ``` ┌───────────────────────────────────────────────────────────────────┐ │ ED ENCOUNTER TAB │ │ [Patient label] [Stage N badge] │ │ Age | Gender | Chief Complaint | Model dropdown │ ├───────────────────────────────────────────────────────────────────┤ │ Stage N Recording — [Listen In] [Pause] [00:23 indicator] │ │ [contenteditable transcript box] │ ├───────────────────────────────────────────────────────────────────┤ │ [✨ Generate Stage N Note] │ ├───────────────────────────────────────────────────────────────────┤ │ ┌─────────────────────────────────────────────────┐ │ │ │ Stage 1 Note [model] [Copy] │ │ │ │ [editable note text] │ │ │ │ ──────────────────────────────────────────────── │ │ │ │ ⚠ Don't Miss — Stage 1 │ │ │ │ • point 1 │ │ │ │ • point 2 │ │ │ └─────────────────────────────────────────────────┘ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ Stage 2 Note [model] [Copy] │ │ │ │ ... │ │ │ └─────────────────────────────────────────────────┘ │ ├───────────────────────────────────────────────────────────────────┤ │ [Refine input] [Refine latest] [Shorter] │ │ [+ Add more (next stage)] [✓ Save & Done (with MDM)] │ ├───────────────────────────────────────────────────────────────────┤ │ ┌─────────────────────────────────────────────────┐ (after │ │ │ 📋 Final Consolidated Note [Copy] │ finalize) │ │ │ [polished single note from edConsolidate] │ │ │ └─────────────────────────────────────────────────┘ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ 💵 Medical Decision Making (2023 E/M) [99284] │ │ │ │ Problems Addressed (moderate): ... │ │ │ │ Data Reviewed (moderate): ... │ │ │ │ Risk (moderate): ... │ │ │ │ Suggested Level: 99284 — rationale... │ │ │ └─────────────────────────────────────────────────┘ │ └───────────────────────────────────────────────────────────────────┘ ``` --- **Files involved** (so a reader can map this to the codebase): | Path | Role | |---|---| | `public/components/ed-encounter.html` | Tab markup | | `public/js/ed-encounters.js` | All client logic (~500 lines) | | `public/js/encounters.js` | Sacred — saveEncounter, sessionStorage, tabMap (2-string touch only) | | `src/routes/edEncounters.js` | `/generate` + `/finalize` endpoints | | `src/utils/prompts.js` | `edEncounterStaged`, `edConsolidate`, `edFinalize` keys | | `src/utils/promptSafe.js` | `wrapUserText` + `INJECTION_GUARD` | | `src/routes/encounters.js` | Generic save infrastructure (saved_encounters table) | | `src/routes/memories.js` | `template_ed` category in `VALID_CATEGORIES` | | `public/js/memories.js` | `template_ed: 'ED Template'` label + `getUserMemoryContext` | | `public/components/settings.html` | `