From 5186e061a8fff79be799d61b482a6af167c9e91e Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 20 Jul 2026 20:34:59 -0500 Subject: [PATCH] Minor additional improvements to the D&D spell extraction prompt. --- docs/integrations/dnd-spell-artifacts.md | 33 +++++++++++-------- docs/internal/modules.md | 10 +++--- .../spells/assets/prompts/instructions.md | 21 +++++++----- .../assets/schemas/dnd_spells_llm.v1.json | 6 ++-- 4 files changed, 41 insertions(+), 29 deletions(-) diff --git a/docs/integrations/dnd-spell-artifacts.md b/docs/integrations/dnd-spell-artifacts.md index 1655b93..b27b9f6 100644 --- a/docs/integrations/dnd-spell-artifacts.md +++ b/docs/integrations/dnd-spell-artifacts.md @@ -58,13 +58,16 @@ occurred. The `spell` value must resolve through the effective SRD-plus-overlay catalog as either a canonical name or alias. Catalog validation accepts aliases but does not rewrite them; unknown fields are rejected. -`effect` and `narrative_description` record what the transcript establishes -about the session as played. They do not correct the table from published D&D -rules or supplement the transcript with model knowledge. When the transcript -contains a nonstandard or disputed ruling, the artifact may preserve the -observed resolution and attribute relevant reasoning to the GM or table; it -must not present that reasoning as a universal game rule. The spell catalog is -name-recognition policy, not evidence for spell mechanics or outcomes. +`effect` and `narrative_description` record the casting declaration and its +immediate resolution as established by the transcript. They do not follow +summoned creatures, persistent spell effects, or other downstream consequences +through the rest of the scene. They also do not correct the table from +published D&D rules or supplement the transcript with model knowledge. When the +transcript contains a nonstandard or disputed ruling, the artifact may preserve +the immediate observed resolution and attribute relevant reasoning to the GM or +table; it must not present that reasoning as a universal game rule. The spell +catalog is name-recognition policy, not evidence for spell mechanics or +outcomes. ## Source References @@ -75,14 +78,16 @@ must not appear after the end unit. Unknown fields are rejected. For each cast, the complete `source_refs` collection identifies the transcript evidence for every factual claim in `caster`, `spell`, `effect`, and -`narrative_description`. A cast declaration and a later resolution may be +`narrative_description`. A cast declaration and its immediate resolution may be cited with separate narrow ranges when intervening units are unrelated. A -reported target, roll, amount, condition, interruption, or outcome must be -supported by the cited units; otherwise the artifact describes only the -supported attempt or declaration. The deterministic validators establish that -ranges are structurally valid and that the spell name is related to cited -text. Semantic claim completeness is an extraction policy and remains subject -to evaluation rather than deterministic proof. +reported target, roll, amount, condition, interruption, or immediate outcome +must be supported by the cited units; otherwise the artifact describes only the +supported attempt or declaration. Later behavior by summoned creatures, +recurring effects, and other downstream consequences are outside the cast +artifact's evidence scope. The deterministic validators establish that ranges +are structurally valid and that the spell name is related to cited text. +Semantic claim completeness is an extraction policy and remains subject to +evaluation rather than deterministic proof. Reference slot keys and accepted file types are defined in [Configuration](../config.md#implemented-production-modules). References are diff --git a/docs/internal/modules.md b/docs/internal/modules.md index 71d99db..700d8f6 100644 --- a/docs/internal/modules.md +++ b/docs/internal/modules.md @@ -160,10 +160,12 @@ failures therefore stop construction before source parsing or an LLM call; campaign references remain separate disambiguation inputs and never become source evidence. -The prompt requires each cast's source references collectively to support all -reported facts, using separate narrow ranges when a declaration and resolution -are non-contiguous. It grounds caster names in in-world identities, using the -player and party references to disambiguate transcript speakers without +The prompt limits each cast to its declaration and immediate resolution; it +does not follow summoned creatures, persistent effects, or other downstream +consequences through the scene. Source references must collectively support all +reported facts, using separate narrow ranges when immediate evidence is +non-contiguous. The prompt grounds caster names in in-world identities, using +the player and party references to disambiguate transcript speakers without treating those references as event evidence. Effects describe the session as played: model rules knowledge cannot supplement or correct the transcript, and nonstandard adjudication is attributed to the GM or table rather than stated as diff --git a/internal/modules/dnd/extract/spells/assets/prompts/instructions.md b/internal/modules/dnd/extract/spells/assets/prompts/instructions.md index ef234b7..7f24c20 100644 --- a/internal/modules/dnd/extract/spells/assets/prompts/instructions.md +++ b/internal/modules/dnd/extract/spells/assets/prompts/instructions.md @@ -2,14 +2,19 @@ Source references must use integer source-unit IDs from the transcript. Provide start_unit_id and end_unit_id for each source reference; the extractor assigns source_id automatically. -For each artifact, its source references must collectively support every -factual claim in caster, spell, effect, and narrative_description. Include the -casting declaration or action and every later transcript unit needed to support -reported targets, saving throws, damage, healing, conditions, interruptions, -and outcomes. When supporting evidence is non-contiguous, provide multiple -narrow source references. Do not use one broad range merely to bridge unrelated -table conversation. If a detail is not supported by the cited transcript -units, omit that detail or describe only the supported attempt or declaration. +Report only the casting declaration or action and its immediate resolution. +This may include an immediately resolved target, saving throw, damage, healing, +condition, interruption, or outcome. Do not follow summoned creatures, +persistent effects, or other downstream consequences through the rest of the +scene. + +For every detail you report, cite all supporting transcript units. The source +references for an artifact must collectively support every factual claim in +caster, spell, effect, and narrative_description. When immediate supporting +evidence is non-contiguous, provide multiple narrow source references. Do not +use one broad range merely to bridge unrelated table conversation. If a detail +is not supported by the cited transcript units, omit that detail or describe +only the supported attempt or declaration. Return only D&D spell-cast artifacts. For each spell cast, identify the in-world caster, spell name, effect, narrative description, and source references. diff --git a/internal/modules/dnd/extract/spells/assets/schemas/dnd_spells_llm.v1.json b/internal/modules/dnd/extract/spells/assets/schemas/dnd_spells_llm.v1.json index dd8544d..2cbe1ef 100644 --- a/internal/modules/dnd/extract/spells/assets/schemas/dnd_spells_llm.v1.json +++ b/internal/modules/dnd/extract/spells/assets/schemas/dnd_spells_llm.v1.json @@ -31,17 +31,17 @@ "effect": { "type": "string", "minLength": 1, - "description": "Concise effect or resolution established by the cited transcript units; do not infer mechanics from general D&D rules knowledge." + "description": "Concise immediate effect or resolution established by the cited transcript units; do not infer mechanics from general D&D rules knowledge or follow persistent downstream consequences." }, "narrative_description": { "type": "string", "minLength": 1, - "description": "Short session-grounded description containing only details established by the cited transcript units." + "description": "Short session-grounded description of the casting declaration and immediate resolution, containing only details established by the cited transcript units." }, "source_refs": { "type": "array", "minItems": 1, - "description": "One or more narrow transcript ranges that collectively support every factual claim in this spell-cast object, including any reported resolution or outcome.", + "description": "One or more narrow transcript ranges that collectively support every factual claim about the casting declaration and immediate resolution in this spell-cast object.", "items": { "type": "object", "additionalProperties": false,