pediatric-ai-scribe-v3/docs/logic/ed-encounters.md

# 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
   `<section id="ed-tab" data-component="ed-encounter">` 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 <span id="ed-rec-stage-num">N</span>
  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 <span id="ed-gen-stage-num">N</span> 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": "<plain-text note>", "dontMiss": [{"point","why"}], "model": "<id>" }
```

The route assembles a structured user message:

```
ED ENCOUNTER — STAGE N
Patient: <age>, <gender>
Chief Complaint: <wrapped>

CURRENT STAGE TRANSCRIPT (may include direct physician asides — preserve and route them per the prompt rules):
<wrapped transcript>

PREVIOUS-STAGE NOTE (baseline to integrate on top of — do not start fresh):
<wrapped previous note>      [only stage 2+]

PHYSICIAN TEMPLATES AND PREFERENCES:    [if any]
<wrapped templates>
```

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": "<plain-text consolidated note>",
  "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": "<id>"
}
```

**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 `<div>` 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` | `<option value="template_ed">` in the category dropdown |
| `public/index.html` | Tab button, lazy-load section, script tag |
| `server.js` | Mounts `edEncounters` route on `/api` |