# Checkpoint 6: D&D Spells Extractor

## Status

This document describes planned work, not implemented behavior.

## 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;
- CLI-level integration test if the CLI path is ready.

Out of scope:

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

## Proposed Stages

### Stage 1: Spell Artifact Schema

Define the D&D spell artifact model.

Initial shape:

```go
type SpellCast struct {
    Player               string      `json:"player"`
    Spell                string      `json:"spell"`
    Effect               string      `json:"effect"`
    NarrativeDescription string      `json:"narrative_description"`
    SourceRefs           []SourceRef `json:"source_refs"`
}
```

Keep this schema inside the D&D spells extract module or a D&D artifact package,
not inside core framework packages.

### Stage 2: Structured Response Schema

Add a structured response schema asset for spell extraction.

The schema should require:

- spell-cast array;
- non-empty player, spell, effect, and narrative description fields;
- at least one source reference per spell cast.

### Stage 3: Prompt Assets

Add embedded prompt assets for D&D spell extraction.

Prompts should:

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

### Stage 4: Process Module Implementation

Implement `internal/modules/extract/dnd/spells`.

The extractor should:

- satisfy the framework `Extractor` contract;
- declare module metadata for pipeline-profile validation;
- build LLM messages from a source document or source chunk;
- call the structured LLM client;
- return artifact candidates with source references;
- attach its validator chain.

### Stage 5: Validators And Tests

Wire deterministic validators:

- schema/shape validation;
- source-reference validation;
- required-field validation if not covered by schema handling.

Add tests using a fake structured LLM client:

- successful spell extraction;
- empty result;
- invalid source reference rejection;
- malformed structured output handling;
- stable output ordering.

### Stage 6: CLI Integration

If the CLI path is ready, add an end-to-end test using:

```sh
notarius run dnd-session --input ./transcript.json --only spells
```

The test should use fake LLM wiring, fixture input, and a named pipeline profile
with a `spells` artifact lane.

## 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, and through
  CLI if the CLI path is ready.

## 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?