# Checkpoint 5: D&D Spells Extractor

## Status

This document describes planned work, not implemented behavior.

## Goal

Implement the first useful extraction 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/extractors/dnd/spells`;
- 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 extractor 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: Extractor Implementation

Implement `internal/extractors/dnd/spells`.

The extractor should:

- satisfy the framework `Extractor` contract;
- build LLM messages from a source document or source slice;
- 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 extract ./transcript.json --input seriatim --extractors dnd.spells --output ./artifacts.json
```

The test should use fake LLM wiring and fixture input.

## 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 extractor/artifact packages and docs.
- The first meaningful vertical slice is available through tests, and through
  CLI if the CLI path is ready.

## Review Questions

- Is the spell extractor 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?