settled-reach/wiki/authoring/culture-authoring-guide.md

# Culture Authoring Guide — The Settled Reach
**Ticket:** #653
**Author:** Mellanie
**Status:** canonical
**Last updated:** 2026-03-13

---

## Purpose

Every NPC in The Settled Reach is voiced through their culture. The voice pipeline (D-138) uses a culture profile as its primary LLM prompt — the culture injector is the single biggest determinant of how an NPC sounds. Culture files are authored once and used thousands of times across every generated NPC in that system.

This guide explains how to author a new culture RON file from scratch. The target: one experienced author can produce a complete, Spike-validated culture profile in approximately one working day.

Three reference cultures exist in `content/global/`:
- `culture-van-maanens-star.ron` — Mid-Reach, freight, working-class pragmatic (the Spike 1/2 reference)
- `culture-vael.ron` — Core-adjacent, administrative/research, institutional-formal
- `culture-osse.ron` — Deep Frontier, extraction industry, terse-utilitarian

---

## Step 1: Establish the cultural parameters (30 minutes)

Before writing a single word of the RON file, answer these five questions from `docs/design/cultural-generation-guide.md`:

1. **Reach Position:** Core / Mid-Reach / Frontier / Deep Frontier
   → Determines authority attitude, institutional density, Commission presence

2. **Economic Base:** Freight / Extraction / Manufacturing / Service / Research / Mixed
   → Determines daily vocabulary, rhythms, what NPCs care about

3. **Settlement Age:** New (< 20 yr) / Established (20-80 yr) / Mature (80-200 yr) / Old (200+ yr)
   → Determines rootedness, architectural character, whether "here" is home

4. **Heritage Root:** Frost / Tide / Iron / Dust / Stone / Vine / Salt
   → Determines spatial grammar and social privacy model (D-104/D-105)

5. **Institutional Ecosystem:** Which institutions are visibly present? Which are resented?

Write these down before you open a RON file. They are the source of truth for everything that follows.

---

## Step 2: Define the voice register (10 minutes)

Derive the voice register from your five parameters. Ask:

- How does authority feel here? (Collegial / Distant / Resented / Absent)
- What is the cost of saying too much? (Social / Physical / Legal / None)
- What earns trust here? (Credential / Shared risk / Repeated interaction / Demonstrated skill)
- What is the cultural mode of emotional expression? (Understatement / Direct / Suppressed / Public)

Write a one-sentence register description. This becomes `speech.register` in the RON.

**Examples:**
| Culture | Register |
|---|---|
| Van Maanen's Star | direct, minimal pleasantries, gets to the point |
| Vael | complete sentences, institutional framing, measured, precise |
| Osse | terse, functional, equipment vocabulary, economy of language |

---

## Step 3: Author the naming conventions (15 minutes)

Naming conventions follow from Reach position + settlement age + economic base:

| Parameter | Naming tendency |
|---|---|
| Core, old settlement | Polysyllabic, family-name-primary, formal phonemes |
| Mid-Reach, mature | Mixed — 1-2 syllables, either name primary depending on sub-culture |
| Frontier, new | Short, work-derived, first-name-only or work-name |
| Extraction industry | Often functional; legal names exist but aren't used |
| Administrative | Family names primary; given names reserved |

**IP check rule:** All names must be checked against:
- Hamilton (Contemporary English given names — avoid)
- Banks (Whimsical/elaborate — avoid)
- Reynolds Firefly (Earth-ethnic echoes — avoid)
- Simmons (Greek/Latin — avoid overt register matches)

Generate 25-35 given names and 15-20 family names. The generator needs variety across playthroughs.

---

## Step 4: Author the voice persona (60 minutes — the core work)

The `voice_persona` field is the LLM instruction that shapes all re-voiced output for NPCs from this culture. This is where one working day of authoring matters most.

### Structure (6-block format, ~200-250 tokens total)

```
PERSONA: You are a [Culture] [role type].

[BLOCK 1 — REGISTER, ~25 tokens]
State the register style, why it exists, one distinguishing marker.

[BLOCK 2 — CULTURAL CONTEXT, ~25 tokens]
One sentence: what shaped this culture's voice. The social or environmental fact.

[BLOCK 3 — VOCABULARY, ~40 tokens]
Exclamations: [closed list — ONLY these expressions. No invented variants.]
Greetings: [closed list]
Address conventions: [family-name-primary, first-name-only, etc.]

[BLOCK 4 — VALUES, ~20 tokens]
Two core values as behavioral instructions. "You do X." not "This culture values X."

[BLOCK 5 — NOT-LIST, ~20 tokens]
2-3 exclusions SPECIFIC to this culture. (Universal NIs cover global constraints.)
Start with: "Do not use..."

[BLOCK 6 — EXAMPLE PAIRS (~70-80 tokens): go in voice_examples field, not here]
```

### The NEVER: block — most important element

**Format:** The NEVER: block is a separate, explicitly labeled section at the END of the persona string. It must not be embedded as a numbered instruction.

```
[positive instructions 1-8]\n\nNEVER: [3-5 explicit negatives defining what this culture does NOT sound like]
```

**Why it matters:** Spike 2 finding — explicit NEVER: blocks are critical for voice quality. Without them, the LLM defaults to register-neutral generic output. The numbered instructions alone are insufficient. The NEVER: section must be visually and structurally distinct — not "8. Do not use..." but a labeled block after the numbered list.

The not-list prevents register leakage. Write it by asking: what does this culture NEVER sound like?

| Culture | NEVER block content |
|---|---|
| Van Maanen's Star | Corporate/institutional language, effusive or polished register, deference to unearned rank, family names in casual use, verbosity |
| Vael | Void-adjacent exclamations (frontier register), casual contractions, sentence fragments, direct emotional expression, physical labor as value ground |
| Osse | Institutional framing or courtesy protocols, formal complete sentences, Commission-world vocabulary, Core-system exclamations, elaboration where a number suffices |

The NEVER: content must be culture-specific. Global constraints (no religious language, no Earth references) go in the universal RULES const — do not repeat them per-culture.

### Writing the persona instructions

Use second-person imperative: "Be direct." not "This culture is direct."

Each numbered instruction should target a DIFFERENT speech dimension so trait modifiers can stack cleanly:
- Instruction 1 → delivery style (brevity, formality)
- Instruction 2 → cultural context (why they speak this way)
- Instruction 3 → address conventions (name usage)
- Instruction 4 → emotional register (how feelings appear in speech)
- Instruction 5 → institutional framing (how authority is referenced)
- Instruction 6 → exclamation vocabulary (closed, explicit list)
- Instruction 7 → trust signal (how the culture verifies credibility)
- Instruction 8 → not-list (what this voice never does)

**Test before committing:** Read the persona out loud. Can you imagine an NPC responding to you from this profile? Would a speaker from this culture be clearly distinct from Van Maanen's Star if you heard both without labels?

---

## Step 5: Author voice examples (20 minutes)

Write 3-5 `(input, output)` example pairs for the `voice_examples` array.

**Input:** A culture-neutral semantic description of an action (same as base text format)
**Output:** That action rendered in the culture's voice

Example pairs are the model's pattern anchors — small LLMs are pattern matchers before instruction-followers. The examples matter as much as the instructions.

**Rules for example pairs:**
1. Cover the range: neutral, positive relationship, refusal/deflection, high-affect
2. Output should be short (1-2 sentences). Long outputs lose the pattern.
3. Each output must be recognizably THIS culture — read them side by side with Van Maanen's Star examples. They should sound like different people.
4. Do not use real NPC names in examples — use generic role references

### Cross-cultural contrast test

Before finalizing examples, run this test. Take the same three base-text inputs and write outputs in Van Maanen's Star, Vael, and Osse voices. If the outputs are hard to distinguish, the culture persona needs sharpening.

**Example inputs for the test:**
- "declines to answer a question about an overnight run"
- "acknowledges a colleague's greeting while continuing to work"
- "thanks a colleague for covering a shift"

| Input | Van Maanen's Star | Vael | Osse |
|---|---|---|---|
| Declines question | "Look, that's not mine to say." | "I'm not in a position to speak to that. You'd want to refer to the relevant operations log." | "Not my section. Ask Grek." |
| Acknowledges greeting | "Hey. Yeah. Catch you at shift end." | "Harthen. Good. I'll be with you in a moment." | "Doss. Yeah." |
| Thanks colleague | "Appreciated. See you at handoff." | "That was well handled. I've noted it." | "Solid. Owe you one." |

If all three rows sound similar, the culture personas need work.

---

## Step 6: Author occasional injections (15 minutes)

`occasional_injections` are cultural vocabulary or speech patterns that should appear occasionally but not always — oath vocabulary, institutional references, equipment ground truth. The composition engine handles frequency; the author specifies what and when.

**Fields:**
- `kind` — a string identifier (e.g., `"oath"`, `"protocol_cite"`, `"equipment_ground"`)
- `clause` — the LLM instruction when this injection fires
- `example` — `Some((input, output))` showing correct usage, or `None`
- `frequency` — float 0.0–1.0 (how often the composition engine fires this injection)
- `suppress_on_tells` — tells that should suppress this injection (e.g., oath suppressed when Guarded)

**Frequency guidelines:**
- 0.25 — Van Maanen's Star oath vocabulary (appears in ~1 in 4 high-affect contexts)
- 0.20 — Vael protocol citation (appears occasionally in procedural exchange)
- 0.15 — Osse equipment ground (appears in work-adjacent contexts)

Start with one injection per culture. More can be added after Spike validation confirms the base persona is clean.

---

## Step 7: Author the tell-tone table (15 minutes)

Each culture profile should include a tell-tone table mapping each `TellCategory` to how that tell expresses in this culture's register. This table is not in the RON file — it's authoring documentation used when tell-context injectors are written.

Include this table in a comment block in the RON file header, or maintain it separately in the culture's authoring notes.

**Format:**

| TellCategory | How it reads in this culture |
|---|---|
| Nervous | [culture-specific description] |
| Angry | [culture-specific description] |
| Friendly | [culture-specific description] |
| Guarded | [culture-specific description] |
| RoutineDeviation | [culture-specific description] |

**Design principle (from D-138):** Humans are humans first. Universal baseline (phenomenon-class behavior) is always readable across cultures. Cultural flavor is conditional and additive — the LLM adds cultural texture only if it doesn't significantly change the information conveyed. Per-culture tell-tone tables are optional enrichment.

---

## Step 8: Validate and commit

```bash
tooling/validate-ron content/global/culture-{id}.ron culture
```

A passing validation confirms:
- All required fields are present and correctly typed
- Trait names are valid enum values
- RON syntax is correct

After validation, the culture profile is ready for Spike 1 prompt testing. Human review of voiced output is required before the culture goes into baked content.

---

## Tell-tone reference tables

### Van Maanen's Star tell-tone table

| TellCategory | Van Maanen's Star-inflected tonal register |
|---|---|
| Nervous | Answers run shorter than usual. Eyes stay on task. Nothing's wrong — just things to do. |
| Guarded | Direct past the point of directness. Closes conversation paths fast without being unfriendly. |
| Friendly | One beat more than the exchange needed. A word of warmth lands casually, not performed. |
| Angry | Steady. Even. The kind of steady that takes effort. Not hostile — just flat in a way that doesn't feel natural for Van Maanen's Star. |
| RoutineDeviation | Unhurried. Unremarkably normal. Like nothing's worth noticing. |

### Vael tell-tone table

| TellCategory | Vael-inflected tonal register |
|---|---|
| Nervous | Sentences become over-complete — more formal than the situation warrants. Qualifications multiply. "As I understand it" appears where it wasn't needed. |
| Guarded | Responses are brief and technically correct. Every question answered with only what was asked. Institutional framing appears even in informal exchange. |
| Friendly | Slightly less formal than baseline — a given name used where a family name would normally appear. The exchange closes with a word of genuine regard. |
| Angry | Register becomes precisely correct — almost pedantically so. The effort to maintain composure shows as over-precision. |
| RoutineDeviation | Procedures are cited where they wouldn't normally be. A person who deviates from routine anchors to institutional language as cover. |

### Osse tell-tone table

| TellCategory | Osse-inflected tonal register |
|---|---|
| Nervous | Words get shorter. Already-minimal speech contracts to one-word answers and physical acknowledgment. The silence between words lengthens. |
| Guarded | Assessment framing appears: "Why do you need to know?" — stated or implied. Eye contact shifts from reading-the-room to reading-you specifically. |
| Friendly | Slightly more than the exchange needed — an extra beat, an unrequested detail, a "good shift" that lands with more weight. Not warm, just more. |
| Angry | Everything slows down. Deliberate. Responses accurate, closed, no opening for follow-up. |
| RoutineDeviation | The opposite of nervous: unusually conversational. When someone is off-routine on purpose, they over-normalize by saying more than usual. |

---

## Checklist: culture profile complete?

- [ ] Five parameters documented (Reach Position, Economic, Age, Heritage Root, Institutions)
- [ ] Register statement authored and distinctive
- [ ] 25+ given names, 15+ family names, phoneme pattern consistent
- [ ] `family_name_used_socially` accurately reflects the culture
- [ ] Voice persona: 8 numbered instructions, ~200-250 tokens
- [ ] Explicit `NEVER:` block at end of persona string (separate from numbered instructions)
- [ ] NEVER block content is culture-specific (not repeating universal constraints)
- [ ] Cross-cultural contrast test passed (Van Maanen's Star/Vael/Osse comparison)
- [ ] 3-5 voice examples authored, range covered
- [ ] At least 1 occasional injection with suppression logic
- [ ] Tell-tone table authored (5 TellCategories)
- [ ] `tooling/validate-ron content/global/culture-{id}.ron culture` passes

---

---

## Addendum: Behavior Modifiers (#634)

*Added Sprint 26. Applies to all culture files after the composable behavior engine (#633) ships.*

### What behavior_modifiers does

The composable behavior engine assembles observable behavior strings from two parts:

```
BehaviorPrimitive.action  +  BehaviorModifier.clause  →  assembled behavior string
```

Example:
- Action: `"moves freight containers"`
- Modifier: `"without wasted motion"` (Van Maanen's Star, `work_pace`)
- Result: `"moves freight containers without wasted motion"`

A culture provides a pool of modifier clauses. When the engine assembles a behavior, it looks for a modifier whose `category` matches the primitive's `modifier_hint` string. If no match exists, it falls back to any modifier in the pool. If no modifiers exist at all, the action text is used as-is.

**Modifier clauses must grammatically trail any action text.** They are appended with a space. Test by mentally substituting different action verbs: does the clause still read naturally?

### BehaviorContext: when to use each tag

Every `BehaviorPrimitive` carries a `context` field that gates when it is eligible for selection. The composition engine filters by context before modifier selection.

| Context | Use for | Example action |
|---------|---------|----------------|
| `OnShift` | Physical task execution, work-site behaviors, role-specific routines | "checks a manifest against a handheld scanner", "guides a freight container into position" |
| `OffDuty` | Break-room behaviors, personal downtime, non-work physical states | "slumps into a break room chair and stares at nothing", "unwraps a meal packet standing at the counter" |
| `Social` | Social-site behaviors (bars, cantinas, communal spaces) — may overlap with OffDuty but specifically at a social venue | "nurses a drink at the end of the bar", "trades short words with a neighbor" |
| `Any` | Behaviors valid in any context — ambient, universal physical states | "rubs the back of their neck", "pauses and looks at nothing for a moment" |

**Decision rule:**
- If the behavior only makes sense on a work site → `OnShift`
- If the behavior only makes sense in a break room or personal space → `OffDuty`
- If the behavior specifically happens at a social venue → `Social`
- If the behavior could appear anywhere → `Any`
- When unsure, prefer `Any` over a specific context — you can always narrow later

### Modifier category vocabulary (the contract)

These seven categories define the interface between primitives (Mellanie, role-action templates) and modifiers (culture authors). A primitive's `modifier_hint` must use one of these strings for a culture modifier to match it.

| Category | What it inflects | Example modifier (Van Maanen's Star) |
|---|---|---|
| `work_pace` | Speed and intensity of physical task execution | "without wasted motion" |
| `physical_manner` | Body language and movement quality during tasks | "without looking up from the task" |
| `social_signal` | Brief acknowledgments made during or between tasks | "with a short nod" |
| `task_completion` | How tasks are finished, wrapped up, or handed off | "and moves on" |
| `environmental_scan` | Awareness or vigilance while in a space | "with one eye still on the floor" |
| `offduty_posture` | Body language and social stance when off-shift | "without making a show of it" |
| `authority_response` | Behavior when supervisors or authority figures are present | "at the same pace as before" |

**The fallback is safe but less targeted.** A primitive with no `modifier_hint` gets a random modifier from the full culture pool. This still produces culturally inflected output — just without category precision. Prefer leaving `modifier_hint` unset over using an incorrect category string.

### Authoring behavior_modifiers for a new culture

**Minimum:** 2 modifiers for each of the 7 categories = 14 modifiers total. Fewer categories will still work (fallback to any), but full coverage ensures every action type gets the right cultural texture.

**Process:**
1. For each category, ask: *How does this culture DISTINCTIVELY express this dimension?*
   - Not "how does any person do this" but "what is the cultural tell for this culture specifically?"
2. Write the clause as a short trailing phrase (4-8 words). Test: does it read naturally after "moves freight containers ___"?
3. Avoid clauses that are too action-specific — they need to trail any verb, not just one type
4. Run `tooling/validate-ron content/global/culture-{id}.ron culture` to confirm syntax

**Three-culture contrast for modifiers** (same as voice persona contrast test):

| Category | Van Maanen's Star | Vael | Osse |
|---|---|---|---|
| work_pace | "without wasted motion" | "with practiced deliberation" | "at extraction pace" |
| physical_manner | "without ceremony" | "with institutional correctness" | "tool already in hand" |
| social_signal | "with a short nod" | "with a measured acknowledgment" | "with a word or a look" |
| task_completion | "and moves on" | "with the relevant entry already updated" | "gear stowed before moving on" |
| environmental_scan | "with one eye still on the floor" | "aware of who is observing" | "pressure and exits both in range" |
| offduty_posture | "without making a show of it" | "maintaining composed reserve" | "with one ear still on the work floor" |
| authority_response | "at the same pace as before" | "with appropriate professional deference" | "without a change in pace" |

If your new culture's modifiers would fit in any of the existing columns above without sounding different — the culture needs more work before modifiers are authored.

### Updated checklist

Add these items to the culture profile checklist:

- [ ] `behavior_modifiers` array populated with at least 2 clauses per category (14 minimum)
- [ ] Each clause tested: grammatically trails "moves freight containers ___" and "checks a manifest ___"
- [ ] Three-culture contrast check: modifiers are clearly distinct from Van Maanen's Star, Vael, and Osse
- [ ] `tooling/validate-ron` still passes after adding modifiers

*Addendum: Sprint 26, #634 (composable behavior content). Category vocabulary established jointly by Gestalt (culture modifiers) and Mellanie (behavior primitives). Add new categories only by agreement between both sides — unmatched categories silently fall back to any modifier.*