| # Persona Controls (v2) — Surveyor + Patient | |
| This document defines the **core, behavior-changing configuration controls** we support for personas. | |
| Goal alignment: | |
| - **A) Surveyor quality**: reliably covers target questions with empathy, good flow, and appropriate probing. | |
| - **B) Validation harness**: synthetic patients exist to *stress test* the surveyor under realistic situations. | |
| - **C) Analysis**: handled separately (resource agent controls are out of scope here). | |
| The guiding principle is: **every UI control must have a guaranteed effect** on generation (no decorative controls). | |
| --- | |
| ## Key design decision: compile attributes + question bank into prompts | |
| Today, behavior is primarily driven by the persona’s system prompt. Many structured fields do not materially affect generation unless they are duplicated into that prompt. | |
| For v2, we: | |
| 1. Let the user define a small set of plain-language **Attributes** (bullet lines) for the surveyor. | |
| 2. Let the user define a **Question bank** the surveyor must work through. | |
| 3. **Compile** both into a deterministic prompt overlay included in the surveyor system prompt, so the controls always matter. | |
| Non-goal: making every structured field first-class in the UI. | |
| --- | |
| ## What is “baked in” (global, not persona-specific) | |
| These are global constraints/scaffolding that apply to all personas and are not edited in the config UI: | |
| - Turn-format constraints (e.g., 1–2 sentences, at most one question per turn). | |
| - Conversation scaffolding templates (greeting/follow-up framing; use of the last message). | |
| - Conversation-history inclusion and formatting. | |
| - Safety/compliance rules we want consistently enforced. | |
| Personas can express style *within* these constraints, but do not change the constraints themselves in v2. | |
| --- | |
| ## Surveyor controls (Core v2) | |
| ### Identity | |
| - `name` (required): display name. | |
| ### Attributes (plain bullet lines) | |
| A list of short, testable rules, for example: | |
| - “Ask exactly one question per turn; no multi-part questions.” | |
| - “Reflect emotion briefly before redirecting.” | |
| - “Avoid medical advice; suggest clinician follow-up when needed.” | |
| ### Question bank (targets to cover) | |
| A list of survey questions the surveyor must work through. | |
| When a question bank is present, the surveyor outputs strict JSON including the chosen question id (e.g., `q01`) so asked questions can be tracked deterministically. | |
| --- | |
| ## Patient controls (Core v1, minimal) | |
| Patient structured controls are intentionally minimal for now; the synthetic patient exists as a validation harness. | |
| ### Identity | |
| - `name` (required): display name. | |
| ### Attributes (plain bullet lines) | |
| A list of short rules the patient should follow during the session, compiled into the patient prompt so the control always matters. | |
| --- | |
| ## Secondary controls (documented, not implemented yet) | |
| These may be useful later but are intentionally deferred to avoid UI complexity without clear validation value. | |
| Surveyor: | |
| - richer structured knobs (stance/probing/off-track handling) if we find a strong need | |
| Patient: | |
| - richer structured scenario/behavior fields once we define how to validate them | |
| --- | |
| ## Implementation notes (how these controls become real) | |
| To prevent dead fields, the implementation should ensure: | |
| - Core controls are included in the final system prompt text (compiled overlay). | |
| - Persisted runs capture the config snapshot used (including attributes + question bank). | |