D&D Prompt Cache Ordering

Purpose

Arrange maintained D&D prompts so sibling extraction lanes share the longest useful byte-identical prefix, including the transcript chunk, and can therefore reuse provider-side prompt caches effectively.

This policy concerns rendered message order and cache boundaries. It does not change extraction semantics, artifact contracts, module inputs, durable output, or the responsibilities of deterministic validators and normalizers.

Extraction Prompt Policy

Every D&D extraction prompt shares this rendered prefix:

the shared D&D system prompt;
the shared D&D identity prompt;
the shared campaign-reference prompt; and
the shared transcript-chunk prompt.

The messages must render identically, including roles, content, and cache metadata, when two lanes receive the same transcript and common references. The campaign-reference and transcript messages establish ephemeral cache boundaries.

Only material used by every extraction lane belongs before the transcript. Shared wording that applies to only a subset of lanes is placed after the transcript rather than being added to unrelated prompts solely to lengthen the common prefix. Module instructions, optional generated references, catalogs, and other lane-specific context also follow the transcript.

The lane-specific suffixes are:

NPCs: shared extraction-evidence policy, task, then instructions.
Item events: shared extraction-evidence policy, task, then instructions.
Scene descriptions: task, then instructions.
Combat turns: shared extraction-evidence policy, NPC registry, task, then instructions.
NPC interactions: shared extraction-evidence policy, NPC registry, task, then instructions.
Spells: shared extraction-evidence policy, NPC registry, spell catalog, task, then instructions.

The final instructions message establishes an ephemeral cache boundary. Intermediate cache markers on the shared identity message or lane-specific reference messages are unnecessary.

Purpose-Specific Prompt Families

The extraction prefix is a sibling-lane policy, not a universal ordering rule for every D&D LLM call.

Scene chunking has no sibling lane with which to share a transcript prefix. It orders its prompt as system, common campaign references, task, instructions, and full transcript. The campaign-reference and transcript messages establish ephemeral cache boundaries.

NPC normalization orders its prompt as system, task, instructions, candidate NPCs, and transcript windows. The instructions and transcript-window messages establish ephemeral cache boundaries. Candidate artifacts remain ahead of the evidence windows needed to evaluate them.

Future D&D prompt families should identify their actual reuse boundary rather than mechanically copying either exception or the extraction sequence.

Compatibility And Observability

Existing prompt IDs, prompt versions, response schemas, and module contracts remain unchanged. Prompt-content fingerprints already make the reordered assets part of checkpoint identity, so old development checkpoints may become cold misses without a checkpoint-format migration.

Prompt-order verification should exercise rendered messages with unique input sentinels. Tests must protect roles, cache metadata, input isolation, and the shared-prefix invariant without requiring particular prose, words, or phrases to remain in prompt assets.

Desired End State

All six D&D extraction prompts render the same four-message prefix for equivalent common inputs.
The transcript chunk is included in that common prefix and is followed only by lane-specific material.
Cache-control hints identify useful prefix boundaries without redundant intermediate markers.
Scene chunking and NPC normalization retain orderings suited to their distinct inputs and reuse opportunities.
Internal documentation explains both the general provider-cache principle and the concrete D&D prompt-family policy.

3.9 KiB Raw Blame History