Document validation defaults and cleanup roadmap

docs/troubleshooting.md

@@ -118,9 +118,10 @@ Symptoms include:
 
 Fix:
 
-- Confirm the selected chunker, extractor, merger, or normalizer declares the slot. The
-  implemented `dnd/scenes` chunker and `dnd/spells` extractor declare optional
-  `roster` and `glossary` slots.
+- Confirm the selected chunker, extractor, merger, or normalizer declares the
+  slot. The implemented `dnd/scenes` chunker and `dnd/spells` extractor declare
+  optional `players`, `party`, and `glossary` slots, plus `roster` as a
+  deprecated compatibility alias for `party`.
 - Use a specific selector when more than one selected target declares the same
   slot: `chunk.context=./context.txt`,
   `spells.extract.context=./extract-context.txt`,
@@ -317,11 +318,31 @@ Explanation and fixes:
   pass to the next pipeline stage.
 - Check `rejected.json` for the stage, lane, module, chunk, validator, reason,
   message, and attempt count.
+- Check `manifest.json` `validator_chains` to see the exact resolved validators
+  and order used for the rejected validation point. The production `dnd/spells`
+  extractor runs JSON syntax, JSON schema, D&D spell shape, source-reference,
+  and source-relatedness validators by default.
+- If the configured chain is not what you expected, inspect the selected
+  binding in config. Omitted `validators` uses production defaults,
+  `validators: []` disables validators for that binding, and a non-empty list
+  replaces the default chain in configured order.
+- Run `notarius config validate --pipeline <id>` to catch unknown validator keys
+  and invalid validator `llm_profile` usage before running the pipeline.
 - Increase a module binding's `retries` only when re-running the same module
   input can reasonably produce an acceptable output.
 - If rejection is deterministic, fix the source input, module configuration, or
   validation policy rather than adding retries.
 
+Common production D&D spell validator reasons:
+
+- `invalid_json`: the raw output is not valid JSON.
+- `json_schema_invalid`: the raw JSON does not match the spell response schema.
+- `invalid_spell_shape`: required spell-cast fields are missing or malformed.
+- `invalid_source_refs`: source references are missing or do not point to valid
+  source units.
+- `spell_not_near_source`: warning-only; the spell name was not found near the
+  cited source text.
+
 ## Retry Exhaustion
 
 Symptoms include: