Design, review, and fix OSCE (clinical simulation) flows in PANaCEa — including patient encounter engines, grading rubrics, transcript handling, clinical reasoning scaffolds, and station configuration. Use this skill whenever working on OSCE mode, clinical simulation, patient encounter UI, OSCE grading, standardized patient interactions, or any live clinical reasoning exercise — even if the user just says 'OSCE is broken' or 'the simulation feedback is wrong'.
OSCE (Objective Structured Clinical Examination) mode must feel like a real clinical encounter with accurate, fair grading. Every patient interaction, transcript, grade, and feedback loop must maintain clinical integrity and psychological safety for learners.
Live Engine (functions/api/osce/live-engine.ts) — Orchestrates real-time patient interaction:
Transcript Pipeline → Persistence → Grading → Feedback:
Grading Loop (functions/api/osce/analysis/) — Multi-dimensional scoring:
| Path | Role |
|---|---|
components/osce/LiveInterface.tsx | Candidate UI; question input, exam selection, timer |
components/osce/AudioInterface.tsx | Voice/audio capture for natural patient interaction |
components/osce/SOAPNoteTrainer.tsx | SOAP note drafting with real-time feedback |
components/osce/DifferentialDiagnosisRanker.tsx | Guides differential reasoning; surfaces omissions |
functions/api/osce/live-engine.ts | Patient logic; state machine; transcript mgmt |
functions/api/osce/live.ts | Candidate session endpoint; auth; state sync |
functions/api/osce/chat.ts | Chat/question API for candidate-to-patient communication |
functions/api/osce/complete.ts | Session completion; triggers grading analysis |
lib/osce/clinicalReasoningScaffold.ts | Decision tree validation; missing reasoning detection |
types/osce-enhanced.ts | Session, transcript, grading data shapes |
config/osce-settings.ts | Station config, time limits, rubric templates |
AUDIT_OSCE_MODE.md | Known issues, recent migrations, compliance checklist |
| Failure | Cause | Fix |
|---|---|---|
| Gemini timeout during live sim | Request payload too large; extended thinking exhausted | Cap thinking tokens; batch patient history summary |
| Grading inconsistency | Scoring dimensions misaligned across stations | Sync config/osce-settings.ts with clinicalReasoningScaffold.ts |
| Lost transcript | Session crash mid-stream; incomplete persistence | Ensure safePrismaDisconnect() in finally blocks; idempotent writes |
| Feedback is vague | Rubric doesn't map to actionable learning | Feedback engine must cite specific missed elements (e.g., "No screening for chest pain risk factors") |
| AI patient breaks character | Temperature too high; response incoherent | Validate Gemini system prompt; use temperature: 0.5–0.7 |
✅ Candidate feels immersed in real clinical encounter ✅ Grading transparent: feedback cites exact reasoning gaps ✅ Transcript complete & auditable (timestamps, all candidate actions) ✅ Session completes in <20s (no Gemini timeout) ✅ Rubric scoring stable across cohorts (inter-rater reliability ≥0.85) ✅ Coaching feedback drives actual learning (post-OSCE score improvement measurable)
clinicalReasoningScaffold.ts mappings match all station rubrics