Methodology RFC: v0.2 coach mode (LLM-driven session intake)

[bpevreall]

Status: rails landed in v0.1 · UI deferred to v0.2
Related: worker/migrations/0004_session_draft.sql, worker/src/routes/intake.ts, worker/src/routes/coach.ts

Context

The architecture review of Phenologue v0.1 surfaced a strong direction: Claude (an LLM) as the conversational coach for session intake, instead of presenting the patient with raw forms. Patients — especially those with chronic pain, ADHD, or anxiety — find clinical-style forms cold and intimidating, and divulge less data than a conversational interface would extract.

v0.1 ships the rails for this: the session_draft table, the /api/sessions/intake API surface (start / patch / commit / void / read), and the /api/coach/intake endpoint stub returning ""coach mode not yet enabled."" The form-based flow at /dashboard/sessions/new and /dashboard/quick-log continues to work and remains the primary path until coach lands.

Goal for v0.2

Implement the LLM-driven session intake on top of the existing draft + intake API. The smallest viable shape:

1. Frontend — a chat-style /dashboard/sessions/coach route. Drop-cap on assistant turns (pattern already in DropCap.svelte), accent-red --accent for assistant voice, mono input box.
2. Backend — replace the stub in coach.ts:POST /api/coach/intake:
   • Load the draft via draft_id
   • Format a system prompt with the current draft state + methodology constraints
   • Call the LLM (Cloudflare Workers AI binding OR Anthropic API pass-through)
   • Parse a structured response: { assistant_message, draft_patches: Partial<DraftState> }
   • Apply the patches via the existing PATCH /api/sessions/intake/:id path
   • Return the assistant message + patches to the client (streamed if possible)
3. Methodology constraints — the LLM must be primed to never:
   • Make medical claims
   • Encourage non-prescribed dosing
   • Skip the methodology-required pre-rating step
4. Eventual commit — when all required fields are captured, the coach offers to commit the draft. User confirms → call POST /api/sessions/intake/:id/commit.

Open design questions

1. LLM provider — Workers AI (Llama-class, free, edge) vs. Anthropic API (better quality, cost, latency). Probably start with Anthropic for accuracy, evaluate Workers AI later.
2. Prompt versioning — should the system prompt itself be methodology-versioned (so coach behaviour doesn't drift between methodology releases)?
3. Patient privacy — what does the coach prompt contain about the patient? Conditions only, no other PII? Need to be explicit.
4. Hallucination guards — the coach should refuse to fill in methodology fields the patient hasn't actually said. Audit log every draft patch with via=coach.
5. Fallback — if the coach can't parse the patient's answer after N tries, drop them back to the form for that field.

Acceptance criteria

• /dashboard/sessions/coach route renders chat UI
• POST /api/coach/intake returns LLM-driven response + patches (no longer stub)
• All coach-applied draft changes auditable via audit_event with metadata.via='coach'
• Methodology constraints documented in the coach system prompt
• A patient can complete a session intake end-to-end via coach without touching the form
• Form-based path at /dashboard/sessions/new continues to work as-is

How to contribute

Prompt design suggestions, hallucination-mitigation strategies, and accessibility considerations for chat-style intake (screen readers, keyboard nav, etc.) are all welcome.