Checkpoint 6: D&D Spells Extractor

Status

This document records the target scope for checkpoint 6. The implemented integration contract is documented in docs/integrations/dnd-spells.md.

Goal

Implement the first useful extract-stage module: D&D spell casts from a Seriatim transcript source document.

This checkpoint should produce the first meaningful vertical slice from real source input to validated artifact output.

Scope

In scope:

D&D spell artifact schema and Go structs;
structured response schema asset;
prompt assets;
internal/modules/extract/dnd/spells;
module metadata/capability requirements for pipeline validation;
source-reference and schema validators in the extractor chain;
fake LLM tests;
runner-level integration tests with fake infrastructure.

Out of scope:

D&D item extraction;
NPC extraction;
combat extraction;
cross-slice deduplication beyond simple deterministic merging;
broad D&D rules validation;
a notarius run command.

Target End State

The repository should contain a real D&D spells extract-stage module at internal/modules/extract/dnd/spells.

The spells module should be registered under the stable extractor key dnd/spells. It should be selectable as a named artifact lane in pipeline configuration, for example a lane named spells whose extractor module is dnd/spells.

The module should translate generic source chunks into spell-cast artifact candidates with this spell payload:

caster;
spell;
effect;
narrative_description.

The LLM structured response should also include source references for each spell cast. The extractor should copy those references into the generic artifact envelope rather than duplicating source references inside the durable spell payload.

The caster is the in-world character or creature casting the spell, not the table speaker. Speaker metadata from transcript source units may be used as optional prompt context when present, but it should not be a required or durable field in the spell payload.

Prompts should:

describe the generic source-unit input format;
explain that source references must use source-unit IDs exactly;
avoid relying on transcript-specific fields except as optional metadata;
request only D&D spell-cast artifacts.

The extractor should attach deterministic validators by default. Validation should cover:

spell payload shape;
non-empty required spell fields;
at least one source reference per spell cast;
source references that validate against the source document.

The module should declare flat capabilities for pipeline validation. Initial capabilities should require chunked transcript source material and provide a D&D spell-cast artifact capability.

Implementation staging belongs in implementation.md.

Fixtures And Tests

The checkpoint should add synthetic fixtures and focused tests for:

successful spell extraction with a fake structured LLM client;
empty spell-cast results;
malformed structured output handling;
invalid source-reference rejection;
stable output ordering;
pipeline-profile selection of a spells artifact lane;
runner integration from Seriatim input through the spells extractor using fake chunk and output modules.

Done Criteria

go test ./... passes.
Seriatim input can flow through the runner into the D&D spells extractor.
Spell artifacts include valid source references.
D&D concepts are contained in extract module/artifact packages and docs.
The spells module can be selected as a named artifact lane in pipeline configuration.
The first meaningful vertical slice is available through tests.
No CLI run behavior is documented or implemented until the CLI path exists.

Review Questions

Is the spell extract module domain-specific without making the framework D&D-specific?
Are source references valid and useful for downstream validation?
Is prompt/schema ownership clear?
Does this vertical slice reveal contract changes needed before adding items, NPCs, or combat?

4.0 KiB Raw Blame History