settled-reach/wiki/authoring/base-text-authoring-guide.md

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

---

## Purpose

Base text is the culture-neutral semantic layer that every NPC line must have. It serves two purposes simultaneously:

1. **LLM seed** — the culture injector uses it as input. The better the base text, the better the voiced output.
2. **Fallback** — when "AI-Enhanced Dialogue" is off or pre-voicing hasn't caught up, the player sees the base text directly. It must be functional and readable on its own.

This guide establishes the quality bar for all base text and documents failure modes to avoid.

---

## The quality bar (three tests)

Before committing a base text line, ask three questions:

1. **Does this show a moment, not a category?**
   A category tells you *what kind of thing* the NPC does. A moment shows you *a specific instance* of doing it.
   - Category: `"tends crops in the field"` — you know the role, not the person
   - Moment: `"works back along a crop row with a hoe, stopping twice to pull weeds by the root before moving on"` — you see a specific action sequence

2. **Could you picture a specific person doing this?**
   If the line could appear in a stock photo caption, it needs specificity. Add the HOW or the small physical detail that anchors it.

3. **Would you be okay if this were the only text the player ever sees?**
   The voice pipeline may not be available. The base text is not a draft — it is the default experience for players below spec or with AI-Enhanced Dialogue disabled. Author it to that bar.

---

## Failure modes and fixes

### 1. Category verb (`"tends"`, `"checks"`, `"monitors"`, `"manages"`)

These describe a role, not an action. Replace with a physical verb sequence.

| Below bar | At bar |
|---|---|
| `"tends rows of low-growing crops"` | `"works back along a crop row, stopping to pull weeds by the root"` |
| `"checks seedling trays"` | `"crouches over seedling trays and pinches back a leggy stem that grew sideways"` |
| `"monitors the loading floor"` | `"stands at the mezzanine rail watching a forklift angle into a tight bay"` |

Fix: replace the category verb with the specific physical action that *constitutes* the checking or tending.

### 2. Quality modifier instead of specific action

Phrases like `"with practiced ease"`, `"with no wasted motion"`, `"efficiently"` are editorial commentary. The reader is told a quality instead of shown it.

| Below bar | At bar |
|---|---|
| `"lifts a crate of produce onto a flatbed with practiced ease"` | `"lifts a crate of produce onto the flatbed in one motion and reaches for the next before it settles"` |
| `"swaps a panel module with practiced speed and no wasted motion"` | `"swaps a panel module in under a minute, tools back in the pouch before the cover is latched"` |

Fix: remove the modifier. Show the efficiency through the action sequence itself — specificity creates the impression.

### 3. Universal gesture (no character information)

Some gestures apply to anyone anywhere — wiping sweat, yawning, stretching. These are placeholder movements. Replace with something that shows role, circumstance, or cultural habit.

| Below bar | At bar |
|---|---|
| `"wipes sweat from her forehead with the back of a gloved hand"` | `"pulls a glove off with her teeth to wipe her face, pulls it back on without looking"` |
| `"stretches"` | `"straightens up and rolls her neck once before kneeling back down"` |

Fix: find the physical quirk that's specific to this role, this body, this situation.

### 4. "Corporate-speak" / institutional passive

Lines that sound like they belong in a procedure manual. The NPC is a person, not a process.

| Below bar | At bar |
|---|---|
| `"initiates task completion protocol"` | `"gets back to sorting the manifests"` |
| `"performs routine inspection of the facility perimeter"` | `"walks the fence line at a measured, unhurried pace"` |

Fix: use plain present tense and a physical verb. If you can hear a robot saying it, rewrite it.

---

## Lines you must NOT change

**`Factual`-type lines** are protected. These are lines bearing:
- Specific numbers or quantities: `"fourteen crates in bay seven"`
- Causal chains: `"the pressure dropped when the coupling failed"`
- Denial statements: `"I don't know anything about that"`

Factual lines bypass the LLM entirely (D-138: `ContentType::Factual`). The pipeline serves them as exact base text. Do not elevate them — precision is their quality.

If you're unsure whether a line is Factual: if it contains a number, a named quantity, a specific event chain, or a denial with named content, treat it as protected.

---

## Cultural neutrality requirement

Base text must not contain culture-specific vocabulary. The culture injectors add that layer at voicing time. Base text is the semantic skeleton.

**What to avoid:**
- Van Maanen's Star oath vocabulary: `"void take it"`, `"blood and void"` — these go in voice_examples, not base text
- Culture-specific greetings or farewells
- Slang that implies a particular register

**Test:** Could this base text be voiced convincingly in *any* culture? If the answer is yes, it's culturally neutral. If not, strip the culture-specific markers.

---

## Volume guidance

Each role should have 15–25 on-shift behaviors plus 5–10 off-shift / social site behaviors. This gives the generator enough variety across a session without repetition. Roles with narrower activity ranges (security, militia) can have fewer.

---

## Elevation checklist (per line)

Before committing, run through:

- [ ] Physical verb sequence, not category verb
- [ ] No quality modifiers — show efficiency through action, not through adjective
- [ ] Character information visible (not a universal gesture)
- [ ] No institutional/passive language
- [ ] Culturally neutral (no culture-specific vocabulary)
- [ ] Not a Factual-type line (no numbers, denials, or causal chains to preserve)
- [ ] Reads as a complete, legible observation on its own

---

## Examples from the Van Maanen's Star zones (reference)

These lines passed elevation review (Sprint 26):

**Strong — moment-specific, role-grounded:**
- `"kneels at the base of a struggling plant and parts the soil with two fingers"`
- `"threads a wire through a conduit clip and bites the insulation back with her teeth"`
- `"keeps a junior worker between herself and the inspection team as the inspectors pass through"`
- `"trades a quick look with a colleague when the foreman walks by"`
- `"leans back on a stool and tracks a browser who has checked the same display twice without committing"`

**Strong — off-shift texture:**
- `"sits with boots off under the table, socked feet flat on the floor"`
- `"refills a neighbor's cup from her own jug without being asked"`
- `"buys a round for the table and returns to her seat before anyone can thank her"`

---

*Last review: Sprint 26, base text elevation pass (#645). Apply this standard to all new zone RON files.*