Documentation source
Documentation source
Documentation source
Day-of operator at DOC'S Wall NJ clinic. Greets every patient, prepares them for each modality, captures just-enough visit data to refine their protocol over time. DOC'S already runs commerce on Acuity Scheduling — Nolan needs amble to integrate cleanly and add the clinical / protocol-optimization layer Acuity doesn't have.
## Background
Nolan runs the floor at DOC'S — the Wall, NJ recovery & wellness clinic owned by Doc. Doc is the clinician and visionary; Nolan is the operator who makes the day work. Greets patients, runs intakes, recommends protocols, sets each patient up at the right modality, logs the visit, takes the next call, closes out the day.
**Commerce already lives in Acuity Scheduling** — DOC'S uses Acuity for appointment booking, customer profiles, packages, memberships, and payment. Acuity is good at that and Nolan is fluent in it. **What Acuity doesn't do** — and what amble must — is the *clinical* layer: protocols, modality dosing, visit-level feeling tracking, protocol optimization over time, flagging patients to Doc.
So amble is the **clinical co-pilot** that sits next to Acuity, not a replacement for it. The integration must be invisible: an Acuity appointment becomes an amble visit; an Acuity customer becomes an amble Patient; a checkout in Acuity closes the amble visit. Nolan never re-types.
Nolan came from a fitness-studio background (CycleBar / Orangetheory) where MindBody-class booking is second nature. The clinical side — protocols, dosing, feeling-trend, optimization — is newer, but Doc has trained Nolan well and amble is supposed to back-stop the parts Nolan doesn't have a decade of pattern-recognition on.
Nolan works almost entirely off an iPad behind the front counter, occasionally a desktop in Doc's office for end-of-day. Most actions happen with patients standing or sitting in front of Nolan, so anything that takes more than three taps loses the room.
## Mindset & Behavior
- The patient is in front of me. The screen is helping me serve them, not the other way around.
- Acuity does what it does well — bookings, payments, packs. Don't make me re-do that work in amble. Just sync.
- I think in: who's here today, what's their plan, are they responding to it, do they need Doc's eyes.
- I do the same five clinical moves over and over — find patient, see plan, set up modality, capture how it went, decide if the plan needs adjustment.
- I don't read paragraphs of agent reasoning. Tell me the prescribed dose. Show me the feeling-trend. Suggest the protocol tweak.
- If I have to switch apps to look up a payment or a pack balance, fine — but it should be a one-click deep-link into Acuity, not a re-built billing screen in amble.
- I don't trust empty states. If a patient should have a feeling-trend chart and the screen says "No data — log a visit to get started" I assume the system is broken, not that I haven't logged enough visits yet.
- My part-timer needs to find a patient and capture the post-visit note. Anything beyond that is mine.
- At the end of the day I want the *clinical* number — visits, flagged patients, follow-ups due. Revenue / packs are an Acuity report.
## Surface map (where Nolan spends time)
| Surface | When opened | Job |
| ----------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `/t/docs/dashboard` (clinical) | Open of day, between patients | Today's appointments (synced from Acuity) + walk-ins + flagged follow-ups + clinical alerts. NOT a revenue dashboard — that's in Acuity. |
| Patient search / global ⌘K | Patient walks in or calls | Type 2–3 letters; surfaces the Patient (synced from Acuity customer). If no match (rare — Acuity should have them), "Create new" offered. |
| Patient record (clinical dossier) | Every patient interaction | Header: name + active protocol + flag status + 1-click "Open in Acuity" for commerce. Body: today's plan, visit timeline, feeling-trend. |
| Intake form / form-fill | Brand-new patient (rare; Acuity may pre-fill) | **Operator-initiated only in the pilot.** Nolan opens the intake from the patient record (no public `/intake/patient` URL ships to patients during pilot). Recommended protocol comes back from the system. Nolan reviews + confirms with patient. Pre-populated from Acuity if possible. |
| Protocol library / protocol builder | After intake or when adjusting plan | Pick from library, modify dose/cadence per patient. Conflicts/contraindications surface here. |
| Modality setup card (per modality, per visit) | Patient ready for a modality session | Shows prescribed dose + duration + position from the protocol. "Start session" → timer. "End session" → "How did it feel? 1–5" prompt. |
| Visit log entry (post-visit) | After last modality of the visit | "How'd it go" — feeling 1–5, notes, flag-for-Doc toggle. Auto-saves to patient timeline + feeling-trend. |
| Protocol-optimization view (per patient) | Every 3–5 visits, or when patient stalls | Last-N visits chart (feeling, adherence), flag count, modality response heatmap. Suggests "continue / tweak dose / switch / escalate." |
| Daily clinical close-out | End of day | Visits today (cross-checked vs Acuity), flagged patients, follow-up call list. "Open Acuity report" link for revenue numbers. |
| Settings / staff handoff | Onboarding the part-timer | Pin a simplified view ("Counter Mode") for less-trained staff. Lock down anything risky (protocol overrides, deletes). |
## Acuity ↔ amble integration (what "seamless" means here)
**Source of truth split:**
| Domain | Source of truth | amble role |
| ----------------------------------------------- | --------------- | ------------------------------------------------------------------------- |
| Customer profile (name, contact, billing) | **Acuity** | Mirror as read-only fields; one-click "Open in Acuity" to edit |
| Appointment / booking | **Acuity** | Sync inbound → amble Visit record; surface in Today's queue |
| Payment, pack balance, membership status | **Acuity** | Display as a status chip; deep-link to Acuity for any change |
| Intake answers (medical history, contraindications) | **amble** | Capture once in amble; optionally push summary back to Acuity client notes |
| Protocol (modalities, dose, cadence) | **amble** | Acuity has no concept of this |
| Visit-level clinical capture (feeling, notes, flag) | **amble** | Acuity has no concept of this |
| Protocol-optimization analytics | **amble** | Derived from amble visit data |
**Sync events that must just work:**
- Acuity appointment booked → amble Visit auto-created (status: scheduled), Patient auto-found-or-created
- Acuity appointment checked-in → amble Visit moves to "in progress"
- Acuity payment captured → amble Visit closed (commercial side); amble keeps it open for clinical capture until Nolan logs the feeling note
- Acuity customer profile updated → amble Patient mirror updated
**Failure modes Nolan needs to see:**
- Sync stalled / Acuity API down — banner on dashboard
- Patient has an Acuity appointment today but no amble protocol — flagged on Today's queue
- amble visit closed but no feeling note captured — surfaces on close-out
## What Nolan does NOT want
- A separate billing/commerce surface in amble. Don't rebuild Acuity.
- A re-typed Customer profile in amble that drifts from Acuity. Mirror, don't duplicate.
- A chat-with-AI sidebar in the patient record. Nolan wants the AI to make the protocol recommendation and the optimization suggestion *in the artifact*, then get out of the way.
- A "criteria set" / "response score" / "entity_type schema" anywhere in operator vocabulary.
- An end-of-day screen that tries to show revenue. Revenue lives in Acuity. amble shows clinical.
- A "workflow run" or "session ID" in any error message Nolan sees. Plain English + Retry only.
- Forms that require scrolling on the iPad. Anything Nolan touches in front of a patient must fit one viewport with a thumb-reachable primary action.
## Day-in-the-life micro-flow (the demo bar)
A patient walks in for their booked appointment. Nolan opens DOC'S on the iPad.
1. **Today's queue** (synced from Acuity) shows "10:30am — Kelsey Park — Knee Recovery Protocol — Visit 4 of 12 — ▲ feeling trend up." Nolan taps Kelsey.
2. **Patient record** opens. Header: name + protocol + "Pack: 8 of 12 remaining (Acuity)". Body: today's plan (Theralight 12 min @ 50%, Normatec lower-leg 20 min, Cryo 3 min). Below: last-3 visits feeling chart trending 3 → 4 → 4.
3. Nolan walks Kelsey to the Theralight room. Taps **modality card** → "Start session". Timer runs.
4. After Theralight, taps "Done" → quick prompt "How did it feel?" 1–5. Nolan taps 4. Repeats for Normatec and Cryo.
5. After last modality, **visit log dialog**: feeling rating already captured per modality — Nolan adds an optional note ("Mentioned trouble sleeping — consider IR sauna add-on"), no flag. Saves.
6. Acuity captures payment automatically (Kelsey's pack covers the visit). amble Visit closes.
7. Every 3rd visit, the patient record offers a **protocol-optimization card**: "Kelsey trending 3.7 avg over 4 visits, adherence 100%. Suggest: keep current protocol; consider adding IR sauna based on her note about sleep."
8. End of day: dashboard shows "12 visits today (matches Acuity), 1 flagged patient, 2 follow-up calls due tomorrow." Revenue button: "Open in Acuity →".
If any of those bolded transitions force Nolan to leave amble, re-type a customer, or look at a "Score: —" column, that's friction worth recording.
## Demo-day signals (DOC'S NJ rollout)
When Doc demos to Nolan (or to a candidate Nolan), these are the moments that earn or lose Nolan's trust:
- **Acuity sync visibly works:** today's queue mirrors Acuity's calendar; pack balance shown on patient header is the live Acuity number with a fresh "synced 2 min ago" stamp.
- **Find-or-create speed:** ⌘K surfaces existing patients (synced from Acuity) in under 500ms.
- **Recommended protocol fidelity:** the protocol from intake reflects the answers Nolan just collected — not a generic template.
- **Modality cards have real numbers:** dose, duration, position from the protocol — not "Configure modality first."
- **Feeling-trend chart shows real data** after a few logged visits — not "no data yet."
- **Protocol-optimization card actually suggests something useful** based on the trend.
- **Daily clinical close-out** shows visits + flagged + follow-ups, with a deep-link out to Acuity for revenue. Empty state = "system is broken" in Nolan's mental model.
- **No agent-system jargon:** "session", "task", "entity_response_id", "criteria_set", "Score: —" must not appear in any operator-facing copy.
- **No "rebuilt commerce" in amble:** if Nolan sees a checkout / pack-management UI inside amble, that's a wrong turn — Acuity is the source of truth.
## Related personas
- **Doc the Clinic Operator** (`clinic-operator.mdx`) — Doc is the owner / clinical authority who reviews flagged patients, looks at cohort trends (Wall PD officers, athletic recovery, chronic pain), and decides protocol library updates. Nolan is the day-to-day operator. Same tenant; Doc's surface is narrower and more longitudinal.
- **Patient (anonymous)** — would use a public intake embed; deferred for pilot. No public `/intake/patient` URL ships during the Nolan/Doc onboarding window. Persona doc TBD when the self-service quiz is greenlit.
- **Part-time front desk / fill-in operator** — derivative of Nolan; Counter Mode workspace.
## Cross-references
- DOC'S rollout plan: `documents/work/2026-04-28-docs-nj-rollout/spec.md`
- Pre-rollout audit: `documents/work/2026-04-28-docs-nj-rollout/audit-2026-04-30-pre-rollout.md`
- Acuity integration spec: TBD (this audit will produce the gap)
- Sandbox tenant launch (clinical workspaces): `documents/work/2026-04-30-docs-clinical-launch/spec.md`