notarius/docs/roadmap/dnd-scene-descriptions.md

D&D Scene Descriptions

Status: Implemented

The durable output contract is D&D Scene Description Artifact Contract.

Purpose

Add a focused D&D artifact that describes each accepted scene with a bounded classification, a concise title, and a concise summary. This is the explicit home for the small amount of source-bounded synthesis useful to downstream applications; scene chunking should not remain the long-term owner of those descriptive fields.

The feature follows ADR-0009. It is intentionally richer than a fact-only occurrence extractor, but every model-produced field has a specific scene-description purpose and is grounded by the exact accepted chunk range.

Desired End State

A D&D pipeline that uses accepted scene chunks can add a dnd/scene-descriptions artifact lane. The extractor runs once per accepted chunk and returns exactly one description for that chunk. The merged, normalized artifact is an ordered list with one independently identified and evidenced scene record for every successful chunk extraction.

Use these production identities:

Concern	Identity
Extractor key	dnd/scene-descriptions
Normalizer key	dnd/scene-descriptions
Artifact kind	dnd/scene-description-list
Durable schema ID	notarius.dnd.scene_descriptions
Durable schema name	notarius_dnd_scene_descriptions_v1
Durable schema version	v1
Durable media type	application/json
Private prompt ID	dnd.scene_descriptions
Private response schema ID	notarius.dnd.scene_descriptions.llm
Private response schema version	v1

The lane uses the existing typed artifact, append-order merge, codec, registration, validator-chain, prompt-asset, retry, and output conventions. It does not introduce a new pipeline stage or a dependency on the durable chunk-map export.

Durable Artifact Contract

The durable payload is a strict object containing a scenes array. The array is ordered by accepted source position. Each scene contains exactly:

• id: the accepted chunk ID, copied deterministically;
• source_ref: the accepted chunk's exact inclusive current-source range;
• kind: one value from the closed scene-kind vocabulary;
• title: a concise source-grounded label for the scene; and
• summary: a concise source-grounded account of the scene's main activity.

The accepted chunk ID is the scene ID. Do not add a second chunk_id field or generate an unrelated scene identifier: this artifact has exactly one record per accepted scene chunk, so the chunk identity is already the stable identity needed for joining with chunk maps and other range-grounded artifacts.

Every fixed object rejects unknown fields. id and source_ref are application-owned evidence and identity fields. The model must not emit or reproduce chunk IDs, source IDs, unit IDs, or ranges.

The extractor maps one successful private response into a single-element durable scenes array before extraction validation. It attaches the current chunk ID and range at that boundary rather than relying on normalization to manufacture required provenance.

Model-Owned Fields

The private model response contains exactly:

• kind;
• title; and
• summary.

It represents one scene object, not a list. An accepted chunk is already the scene boundary, so the extractor must neither split the chunk nor return multiple descriptions. It must not return an empty result; inability to classify or describe the chunk is an extraction failure subject to the configured retry and rejection policy.

title should be a short, distinguishing phrase rather than a sentence, chapter number, or generic label such as “Scene.” It may use names and places established by the transcript or optional campaign references, but must not invent a proper noun to make the title more colorful.

summary should briefly state the main activity and material transition or outcome established within the chunk. It must not add analysis, inferred motives, hidden state, future consequences, relationship claims, or facts from outside the chunk. Do not require a structured participant list, encounter outcome, location, mood, or confidence field.

Scene-Kind Vocabulary

Use this closed vocabulary:

Kind	Meaning
combat	Active combat materially organizes the scene, including initiative-like exchanges or sustained hostile action. Planning a fight or discussing a completed fight is not combat by itself.
narrative	Current-session in-world play that is not principally active combat, a prior-session recap, or sustained out-of-character session discussion. This includes exploration, travel, dialogue, investigation, planning in character, and aftermath.
recap	The scene's organizing purpose is to recount events from a previous session for the table. An in-world character recounting history during current play remains narrative.
meta	The scene's organizing purpose is sustained out-of-character discussion about the game or session rather than advancing current in-world play.

narrative is the default category for actual current-session gameplay that does not meet another definition. The model must choose exactly one kind and must not emit an uncertainty or mixed category.

Residual Mixed-Scene Policy

Scene chunking should normally separate sustained transitions between kinds. When an accepted chunk nevertheless contains more than one kind, classify the activity that best describes the chunk's organizing purpose and main current-session progression:

1. use combat when active combat is a substantive central activity, even if the chunk includes brief setup, rules clarification, or immediate aftermath;
2. use recap when recounting a previous session is the chunk's primary table purpose, not merely a brief reminder before current play;
3. use meta when sustained out-of-character session discussion is primary and the chunk contains no more than incidental in-world progression; and
4. use narrative for all remaining current-session in-world play.

Brief table talk, dice resolution, rules clarification, jokes, or administrative comments are incidental to the enclosing gameplay scene and do not make it meta. A short recollection used to orient current action does not make a scene recap.

This precedence resolves residual ambiguity for description. It does not alter the accepted chunk boundary or authorize the extractor to conceal a demonstrably poor scene plan.

Evidence, References, And Prompt Boundary

The exact accepted chunk range is the evidence for all three model-owned fields. Do not ask the model for finer-grained source ranges, and do not use campaign references as evidence.

The lane requires no generated artifact reference. Existing optional D&D campaign references may be exposed through the established shared slots when they help disambiguate names or setting terms in titles and summaries. They must not introduce events, participants, or claims absent from the current chunk. Do not require an NPC registry: structured participants remain owned by NPC and NPC-interaction artifacts.

Follow the established D&D prompt ordering and prompt-cache boundary:

1. shared D&D system and identity policy;
2. stable campaign references, including explicit empty placeholders;
3. lane task and classification instructions; and
4. the variable current-chunk transcript last.

Factor wording genuinely shared with other D&D modules into existing shared prompt assets. Keep scene-kind definitions and mixed-scene policy in scene-description-owned assets rather than broadening unrelated extractors. Do not render the existing shared extraction-evidence asset in this lane: that asset instructs the model to emit source ranges, while scene identity and the entire accepted chunk range are attached deterministically by the application. This is a deliberate exception to the shared extraction prompt sequence, not permission to duplicate compatible shared wording in lane-owned assets.

Merge And Normalization

Use the existing append-order merge behavior. Normalization remains deterministic and must:

• validate every record against the current source document;
• require an exact closed-vocabulary kind without case-folding or repairing an invalid model value;
• trim surrounding title and summary whitespace without otherwise rewriting their prose;
• order scenes by source-document position, with accepted chunk ID as the deterministic tie-breaker;
• remove only completely identical duplicate records; and
• reject conflicting records that reuse one scene ID or exact source range with different model-owned content.

Normalization must not combine adjacent scenes, regenerate titles or summaries, change classifications through heuristics, or infer missing records. Exact deduplication is defensive cleanup, not semantic reconciliation.

Validation And Quality

Provide the same layered production validation used by other typed D&D artifacts:

• valid JSON and strict private/durable shape;
• exactly one private description and one mapped durable scene per chunk;
• closed kind vocabulary;
• non-empty, trimmed title and summary;
• non-empty accepted chunk ID;
• a current-source range exactly equal to the extraction chunk range;
• source-relatedness checks for title and summary; and
• strict durable JSON Schema validation after normalization.

Shape, identity, enum, and source-range violations are deterministic rejections. Source-relatedness should initially remain warning-only unless evaluation establishes a reliable rejection rule. Diagnostics must be bounded and must not copy transcript or campaign-reference content.

Evaluate the lane on a small human-reviewed transcript set covering all four kinds, incidental table talk, brief and sustained recap, combat setup and aftermath, mixed residual chunks, sparse scenes, proper-noun ambiguity, and unsupported synthesis. Review classification agreement, title usefulness, summary fidelity, evidence attachment, and performance on the cost-effective models Notarius is intended to support. Human evaluation is a development aid, not an exact-text CI oracle.

Tests should protect structural contracts, deterministic mapping, normalization, validation, prompt assembly, registration, and one assembled production workflow. Do not assert exact generated prose or use brittle prompt length and shared-prefix change detectors.

Relationship To Scene Chunking

This artifact becomes the intended owner of scene kind, title, and summary. The existing dnd/scenes chunker remains unchanged in this scope. Downstream consumers should prefer the normalized scene-description artifact over chunk annotations for kind, title, and summary.

Removing descriptive fields from the chunker is a separate follow-on scope. It requires its own review of chunker prompt quality, warning/validator consumers, cache behavior, and the compatibility implications of changing accepted plan annotations. Do not couple that migration to the initial artifact lane.

Likewise, do not make combat extraction conditional on scene kind in this scope. A later ordered-pipeline feature may consume the accepted normalized scene-description artifact and no-op combat extraction for non-combat scenes without making generic chunk materialization depend on D&D classification.

Documentation Ownership

Once implemented, the durable contract belongs in docs/integrations/; selectable keys, optional campaign-reference bindings, and default validator chains belong in configuration documentation; and prompt, module, validator, and pipeline mechanics belong in current internal documentation. A maintained D&D example should demonstrate scene chunking and scene-description extraction without presenting chunk annotations as the durable description contract.

Non-Goals

This scope does not:

• change scene boundaries or run a second chunker;
• ask the model for IDs, source ranges, segment numbers, or evidence selection;
• add structured participants, locations, encounters, outcomes, moods, confidence, or relationship fields;
• duplicate NPC or NPC-interaction extraction;
• require an NPC registry or another generated artifact;
• enrich descriptions from campaign references when the chunk lacks support;
• semantically merge or reconcile adjacent scene descriptions;
• minimize the existing scene chunker in the same change;
• gate combat extraction by scene kind;
• make scene descriptions generated references for later steps;
• change chunk-map export, chunk caching, or plan validation; or
• introduce a DAG, a new pipeline stage, or a new reference mechanism.