Docs: define core persona knobs

docs/README.md

@@ -5,6 +5,7 @@ These short guides are all you need to extend the AI Survey Simulator:
 - `overview.md` — architecture summary, major components, and repository map.
 - `development.md` — setup, runtime instructions, and implementation guidelines.
 - `persistence.md` — persistent run history + persona CRUD design (HF `/data` now, Railway later).
+- `persona-knobs.md` — persona configuration knobs (core v1 vs deferred) for Surveyor + Patient.
 - `roadmap.md` — current status and prioritized future work.
 
 Keep documentation lean: update the relevant file when behavior changes or priorities shift.

docs/persona-knobs.md

@@ -0,0 +1,136 @@
+# Persona “Knobs” (v1 Core) — Surveyor + Patient
+
+This document defines the **core, behavior-changing configuration knobs** we will support first 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 knobs are out of scope here).
+
+The guiding principle is: **every UI field must have a guaranteed effect** on generation (no “decorative” persona metadata).
+
+---
+
+## Key design decision: compile structured knobs into prompts
+
+Today, the LLM behavior is primarily driven by the persona’s `system_prompt`. Many existing YAML fields do not materially affect generation unless they are manually duplicated into that prompt.
+
+For v1, we will:
+
+1. Define a small structured schema of core knobs (below).
+2. **Compile** those knobs into a deterministic “persona overlay” section that is included in the model’s system prompt.
+3. Keep a **system prompt preview** in the UI showing the exact final system prompt text that will be sent.
+
+This preserves flexibility (freeform prompt editing) while ensuring the structured knobs always matter.
+
+Non-goal: making every current YAML field first-class.
+
+---
+
+## What is “baked in” (global, not persona-specific)
+
+These are global constraints / scaffolding that apply to all personas and are not edited in the persona editor:
+
+- Turn-format constraints (e.g., “ask at most one question”, “1–2 sentences”) and token/temperature defaults.
+- Conversation scaffolding templates (greeting/follow-up framing; use of the last message).
+- Conversation-history inclusion and formatting (e.g., max history window).
+- Safety/compliance rules we want consistently enforced across personas.
+
+Personas can express style *within* these constraints, but do not change the constraints themselves in v1.
+
+---
+
+## Surveyor persona knobs (Core v1)
+
+These should be exposed as first-class fields and compiled into the surveyor system prompt.
+
+### Identity
+- `name` (required): display name.
+- `description` (optional): short one-liner shown in selectors.
+
+### Survey behavior
+- `stance` (dropdown): `empathetic_researcher | neutral_clinical | time_efficient`.
+- `question_strategy` (dropdown): `sequential | adaptive_followups | conversational_cover_all`.
+- `probing_policy` (multi-select):
+  - `clarify_timeline`
+  - `ask_examples`
+  - `quantify_frequency_severity`
+  - `reflect_emotion`
+  - `summarize_and_confirm`
+- `empathy_style` (dropdown): `validating | neutral | supportive_brief`.
+- `off_track_handling` (dropdown): `gentle_redirect | one_vent_then_redirect | hard_redirect`.
+- `sensitivity_handling` (multi-select):
+  - `acknowledge`
+  - `offer_skip`
+  - `normalize`
+  - `avoid_advice`
+
+### Freeform prompt
+- `system_prompt` (required): human-editable base prompt (still important).
+- `system_prompt_addition` (optional, per-run): already supported in the configuration UI; stays as run-level override.
+
+---
+
+## Patient persona knobs (Core v1)
+
+These should be exposed as first-class fields and compiled into the patient system prompt.
+
+### Identity
+- `name` (required): display name.
+- `description` (optional): short one-liner shown in selectors.
+
+### Scenario / health situation
+- `conditions` (list): e.g., `Type 2 diabetes`, `asthma`.
+- `medications` (list): e.g., `metformin`, `albuterol`.
+- `care_context` (short text): e.g., “primary care follow-up”, “recent ER visit”.
+- `recent_events` (short bullets): key timeline anchors used to answer questions realistically.
+
+### Barriers / constraints
+- `barriers` (multi-select):
+  - `cost`
+  - `transport`
+  - `time`
+  - `insurance`
+  - `digital_access`
+  - `language`
+  - `stigma`
+
+### Conversational behavior
+- `cooperativeness` (ordinal): `forthcoming | mixed | guarded`.
+- `emotional_stance` (dropdown): `anxious | frustrated | neutral | optimistic`.
+- `verbosity` (dropdown): `brief | normal | detailed`.
+- `health_literacy` (dropdown): `low | medium | high`.
+- `recall_certainty` (dropdown): `confident | mixed | uncertain`.
+- `digression_tendency` (dropdown): `on_track | occasional_anecdotes | tangential`.
+
+### Freeform prompt
+- `system_prompt` (required): human-editable base prompt.
+- `system_prompt_addition` (optional, per-run): already supported in the configuration UI; stays as run-level override.
+
+---
+
+## Secondary knobs (documented, not implemented in v1)
+
+These may be useful later but are intentionally deferred to avoid UI complexity without clear validation value.
+
+Surveyor:
+- terminology level (plain/mixed/clinical-with-explanations)
+- pacing (brief/normal/thorough) beyond global constraints
+- explicit consent/confidentiality micro-scripts as toggles
+
+Patient:
+- privacy skepticism toggle (“Why do you need this?”)
+- quirks (interrupts, under-reports symptoms, minimizes pain)
+- richer biography fields (occupation, family structure) unless used for study design
+
+---
+
+## Implementation notes (how these knobs become real)
+
+To prevent dead fields, the implementation should ensure:
+
+- All core knobs are included in the final system prompt text (compiled overlay).
+- The UI shows a prompt preview so users understand the effective configuration.
+- Persisted runs capture the persona snapshot and the prompt overlay used (already supported by run snapshots).
+