Narraitor: Skill for Claude Code

Narraitor prompt template governance

1. Purpose

Keep every prompt findable, typed, evaluated, and reversible. A prompt is production behavior: it ships through a registry and gates, not as a string edit.

2. When to use

Any create/edit/delete of prompt text; any change to what context a prompt receives; reviewing a PR that touches src/lib/promptTemplates/ or src/lib/promptContext/.

3. When not to use

• Judging output quality of an existing template → narraitor-ai-quality-discipline (this skill consumes its protocol as the eval gate).
• Generation config (temperature/tokens/model) → that's src/lib/ai/config.ts + change-control, not template governance.

4. Inputs required

The template diff; the context fields it reads; the eval log (or a plan to produce one).

5. Procedure

The registry (where prompts live — nothing lives elsewhere):

• Narrative templates: src/lib/promptTemplates/templates/narrative/* (scene, initial scene, action, transition, player-choice, choice-type, skill-acknowledgment, major-event guidelines), registered by id through src/lib/promptTemplates/narrativeTemplateManager.ts → getNarrativeTemplate(id) (throws on unknown id).
• Ending templates: src/lib/promptTemplates/templates/endingTemplates.ts.
• Context assembly + token measurement: src/lib/promptContext/ (tokenUtils.ts estimates a string, promptCalibration.ts builds the DevTools snapshot, inventoryContextBuilder.ts trims inventory to a caller-supplied tokenLimit). Nothing here budgets or trims the assembled prompt.
• Reference examples: src/lib/promptTemplates/examples/.

HARD RULE: Prompt experiments may output registered, evaluated templates only. They may not hardcode one-off prompt strings into narrative-generation code paths (generators, routes, components). If you see an inline prompt string outside the registry, that is a defect — file it.

The gates, in order:

G1 INPUT CONTRACT — the template reads only fields of NarrativeTemplateContext
   (src/lib/promptTemplates/templates/narrative/context.ts). Need a new field?
   Extend the type deliberately; never smuggle data through an existing string field.
G2 LEAKAGE — no feeding the prompt state the narrative shouldn't know:
   other characters' hidden info, meta/system state, raw store internals, player-secret
   data. toneSettings is opaque to templates (forwarded, never field-accessed) — keep it so.
G3 DETERMINISM EXPECTATIONS — state what varies (prose) vs what must be stable
   (structure the parser relies on: headings, JSON shape, choice markers). Changing
   stable structure means checking every parser in src/lib/ai/*parse*/*normalize*.
G4 EVAL — run the narraitor-ai-quality-discipline evaluation protocol (its section 5
   is the single home of the matrix minimums — cite it, don't restate numbers).
   Record in the eval log.
G5 REGRESSION — compare against excerpts saved in earlier eval logs. Old strengths
   must survive. WARNING: src/lib/promptTemplates/examples/ is a few-shot library
   injected INTO prompts (exampleLibrary.ts) — it is NOT a regression corpus, and
   editing it changes live generation behavior.
G6 COST/LATENCY — measure the delta yourself. Nothing enforces a prompt budget, and
   no allocator will trim your template back. Components are bounded only where they
   are assembled (the caller slices the segment window, getLoreContext defaults to 20
   facts, buildInventoryContext trims to a tokenLimit); the assembled whole is never
   trimmed. Estimate with estimateTokenCount (src/lib/promptContext/tokenUtils.ts),
   then check a real request in the DevTools calibration panel, which
   recordRequestCalibration (src/lib/ai/narrativeGenerator.calibration.ts) feeds with
   estimated vs provider-reported prompt size. DEFAULT_TOTAL_BUDGET (80000) is that
   panel's yardstick, not a ceiling. Only narrativeGenerator and choiceGenerator call
   recordRequestCalibration, so the panel is blind to ending templates —
   endingGenerator never publishes a snapshot, and a stale narrative reading will sit
   there looking like yours. For an ending-template change, estimateTokenCount is the
   whole measurement. Put the before/after in the eval log — a template that grows
   context grows every turn's cost and the 5-8s prose wait.
G7 INTEGRATION — at least one eval cell through the real /worlds/[id]/play loop and
   unit tests green (template __tests__ pin assembly, not prose).