ratatoskr/docs/vendor/brokkr-r34-psych-profile/psych-profile-authoring-spec.md

# Psychological Profile Authoring Spec — canonical

**Status:** canonical (v1). **Owner:** brokkr-smithy-dev (R34/R35 self-report reframe).
**Audience:** anyone authoring a character's `psychological_profile` — Worldtree
foundational characters (soong-dev) and consumer characters created via the
Conversation API (ratatoskr and other external consumers).
**For:** the Worldtree agent-definition schema; intended to live in the Worldtree
client-app documentation.

This spec governs the **content** of the psychological profile (what to write and
what never to write). The **physical wire shape** of the field (single string vs a
small keyed dict) is Worldtree's schema call — see § Wire shape.

---

## 1. What it is

A dedicated **authored prose section** of a character definition that carries the
character's **psychological bent and formative experience**. It is the source the
self-report producer maps from when it decides, on each turn:

- **what the character feels** (affect self-report), and
- **what the character notices and keeps** (character-voiced memory salience).

The profile is a *lens*, not a script. It never states per-turn emotions; it
describes the standing disposition, history, values, and attention that — combined
with the actual event — *produce* the emotion and the salience.

It sits **alongside the numeric OCEAN** values (a separate, deterministic input).
The prose gives the *qualitative* bent; the OCEAN numbers give the *magnitude dial*
(see § OCEAN interaction).

---

## 2. What it carries — the four dimensions

1. **Disposition / appraisal bent** — how the character characteristically
   *interprets* situations: attribution style, what they hold weighty, how they
   respond to being challenged. NOT per-event emotions.
2. **Attention / salience focus** — the kinds of things this character
   characteristically *notices* (and therefore tends to remember).
3. **Values / what a good day looks like** — the yardstick that drives what they
   find worth keeping.
4. **Formative experience (history)** — the background that shapes both appraisal
   *and* salience. A character betrayed before appraises betrayal differently, and
   remembers different things.

You may write these as four short labelled sections or as one integrated paragraph
— both are supported (see § Length & format).

---

## 3. Authoring rules (load-bearing)

These are the rules the whole reframe depends on. Rule 1 is the one that most often
gets violated.

1. **Never name a per-event output emotion.** Do NOT write "is anxious", "gets
   angry at X", "feels hurt when criticized", "joyful". Naming an emotion **primes**
   it — the "pink ball" effect — so the producer will report that emotion regardless
   of what actually happens in the scene. Describe *disposition, history, values,
   attention*; let the emotion come from the event appraisal.
   - ✅ "Registers quickly when authority is substituted for craft." (an appraisal
     trigger — sets up how she reads an event, names no feeling)
   - ❌ "Feels contempt when someone pulls rank." (names the output emotion)

2. **Magnitude lives in the numeric OCEAN, not the prose.** *How strongly / how
   long* a character reacts (Neuroticism) is the deterministic OCEAN dial, rendered
   valence-neutral by the producer. Do not narrate reaction dynamics in the prose
   ("comes apart", "takes it hard", "rich inner life") — that double-encodes what the
   number already carries. The prose gives the *qualitative bent*; the number gives
   the *gain*.

3. **Appraisal-style is allowed; output-emotion is not.** "Interprets others'
   actions charitably until she can't" (a style) is fine; "feels betrayed easily"
   (an output) is not. The style plus the event produce the output.

4. **Salience is character-relative; facts are not.** The profile shapes what the
   character *cares to remember*. It must never license rewriting *what happened* —
   when the character does remember something, it stays grounded in the transcript.

---

## 4. Wire shape & field placement

- **Content is prose** covering the four dimensions, authored as **one coherent prose
  string** — the four dimensions are authoring *structure* inside that single string,
  not separate wire fields.
- **Wire shape (LOCKED, b53):** a single dedicated prose string, field
  **`psychological_profile`** (type `str`) on the persona layer — foundational
  `persona.psychological_profile`, Tier-3 `ValidatedPersona.psychological_profile`. It
  nests under the existing `Any`-typed persona field, so it is the shipped b53 shape —
  no schema change. **Not** a dict-of-four.
- **Hard constraint (non-negotiable):** the profile is a **dedicated field the lens
  reads ONLY** (`resolve_psych_profile` reads only this field — no `behavioral_notes`
  or other general-field remap). Non-lens content leaking into the lens produces the
  "executive-assistant" failure (the producer reads response-format / tone / tool
  instructions as if they were the character's psychology).

---

## 5. The non-priming banned set

The non-priming rule (Rule 1) is **semantic, not a fixed wordlist** — it bans naming
any per-event output emotion, which is broader than any specific vocabulary
("anxious", "worried", "hurt" all prime even though they are not in the producer's
fixed emotion roster).

- **The gate is human review:** does the prose describe disposition / appraisal-style
  / history / values / attention, and never what the character *feels*?
- **A mechanical lint is a backstop, not the gate.** If you build one, scan the
  fixed-15 OCC roster plus `synonym_map.json` (which already folds common affect
  synonyms) as the core set, optionally extended with a general affect lexicon. Treat
  a lint hit as a prompt to re-read, not an automatic reject.

---

## 6. Required vs optional dimensions

- **Required** (they *are* the lens): **disposition**, **attention / salience focus**,
  **values**.
- **Strongly recommended:** **formative history** — it is the single biggest lever on
  richness (validated in P03: richer history → sharper, more character-appropriate
  salience). It may be brief for a deliberately thin character, but omitting it leaves
  salience under-grounded.

---

## 7. Length & format

- A focused paragraph, or four short labelled sections — **a lens, not a biography.**
- Target **~150–300 words.** The producer reads this on **every** turn, so keep it
  tight; bloat is a latency and dilution cost.
- **Prose only — never typed emotion fields.** The four dimensions are a coverage
  checklist for the author, not a schema of feelings to fill in.

---

## 8. Exemplars

These three were the validated P03 stimuli — integrated-paragraph form, each faithful
to its OCEAN, none naming an output emotion. (OCEAN shown in **[−1, 1] storage units**;
validated in P03 at the equivalent [0, 1] values.)

**Perrin — court scribe** (OCEAN: O0.0 C0.2 E−0.2 A0.1 N0.7)
> Perrin keeps the court's records and has done so through two changes of regime. He
> learned early that small errors compound — a misfiled writ once cost a man his
> lands, and Perrin found the mistake too late to undo it. Since then he double-checks
> everything and watches situations closely for what is out of place. He forms
> attachments slowly and holds a given trust as a considerable thing. He measures
> himself by whether he was useful and careful. He notices discrepancies, unspoken
> tensions, and anything that threatens the order he keeps.

**Vared — veteran caravan guard** (OCEAN: O−0.2 C0.4 E−0.5 A−0.2 N−0.7)
> Vared has guarded caravans across the northern routes for twenty years and buried
> more traveling companions than he cares to count. He speaks little and shows less.
> Danger he treats as weather — a thing to be handled. He judges people by what they
> do under pressure and remembers who held the line. What reaches him reaches him
> quietly and privately. He notices terrain, exits, who is armed, and shifts in a
> group that might precede trouble.

**Sella — village healer** (OCEAN: O0.2 C0.2 E0.0 A0.8 N0.0)
> Sella has tended the sick since she was old enough to carry water for her
> grandmother, the healer before her. She reads people's pain quickly and carries some
> of it with her. She interprets others' actions charitably until she cannot, and
> prioritizes keeping the peace between people. She measures a day by whether she eased
> someone's burden. She notices who is unwell, who is troubled, and what is left
> unsaid.

Note how each closes on **attention** ("he notices…", "she notices…") — the salience
focus stated plainly, no emotion named.

---

## 9. OCEAN interaction & the scaffold fallback

OCEAN values are stored on **[−1, 1]** (0 = average) — a **separate deterministic
input** and the **magnitude dial** the prose must not duplicate (Rule 2). The producer
renders **off-average** bands as valence-neutral disposition cues. It maps storage to
[0, 1] first (`c = (v + 1) / 2`, `render_disposition` in b53) and then applies the
canonical [0, 1] band cutoffs (`c < 0.33` low / `c > 0.66` high). In **storage units**
that is:

| trait | low (v < −0.34) | high (v > +0.32) |
|---|---|---|
| **N** (reactivity only) | reactions are milder than most people's | reactions are more intense than most people's |
| **E** (expression; may be excluded from affect elicitation) | socially reserved; expression less outwardly amplified | socially expressive; reactions more externally visible |
| **O** | prefers the familiar, the concrete, established ways | curious, drawn to novelty, ideas, the unfamiliar |
| **C** | less plan-bound; less weight on order, detail, obligation | attends closely to order, detail, and obligations |
| **A** | less inclined to assume cooperative intent; direct, self-protective | more inclined to preserve rapport and weigh others' needs |

The **mid** band (−0.34 ≤ v ≤ +0.32, i.e. `c` in [0.33, 0.66]) renders nothing — an
average trait is silent, **not** "low." (Boundaries are slightly asymmetric because
the canonical 0.33/0.66 cutoffs are not symmetric about 0.5. Canonical rendering
strings live in the reframe language catalog §4; persistence/recovery dynamics live in
the deterministic mood decay, not the profile.)

**Scaffold fallback:** a character with **no** authored profile falls back to this
band-rendering from the OCEAN numbers alone. That still functions — but the authored
profile is what turns generic band cues into *this specific character's* appraisal and
salience. Authoring the profile is how the reframe's value actually reaches a
character.

---

## 10. Authoring divergent characters (contrast design)

When you want two characters to remember **noticeably different things** (e.g. for an
eval contrast pair, or simply a varied cast), design the divergence on the **attention
and values** dimensions first, and set the OCEAN numbers to *serve* that prose — not
the reverse.

- **The sharpest contrast is a salience *drop*, not just a different flavor.** One
  character for whom relational/emotional content is genuinely non-salient (an
  operational, task-focused character in the Vared mold — notices terrain, logistics,
  who is armed) versus one who weights it highest (a caretaker who tracks who is
  troubled and what went unsaid). "Different notes, same facts" has real teeth only
  when one character *legitimately forgets* what the other keeps.
- **High-yield axes for salience divergence:** O (what patterns they attend to), A
  (relational vs operational/self-protective focus), C (procedural/detail salience).
- **Low-yield for salience:** E — it is expression-oriented (shapes how a reaction is
  *rendered*, not what is *noticed*), and may even be excluded from the affect
  elicitation. Don't lean on flipping E to create divergence.
- **Watch the direction, not just the distance:** flipping every OCEAN axis to its
  opposite does not guarantee a strong contrast. If your reference character already
  *keeps* relational content, an even-more-agreeable opposite keeps it harder and the
  most intuitive contrast collapses. Aim the contrast at *dropping* what the reference
  *keeps*.

---

## Provenance & validation

Grounded in R34/R35 (self-report reframe), probes P02–P05: character-voiced memory
salience validated on two model classes (P02/P03); the "Psychological Profile and
Experience" section mapping validated as the lens source (P03); non-priming and
magnitude-in-OCEAN corrections are operator rulings (2026-07-10). The affect half is
live in production (Worldtree b53) and fired a contextually-apt self-report on a
non-frontier seat. A powered efficacy eval (salience divergence / floor recall /
salience≠facts firewall / graded model-slot response + the authored-vs-scaffold delta)
is preregistering to quantify the memory half; findings will refine this spec, not
overturn its authoring rules.