Summary
Two independent documentation defects in skills/pipelines/explainer/:
1. Fictitious submit function (3 files)
idea-director.md:132, script-director.md:210, and scene-director.md:229 each tell the agent to call handle_explainer_{idea,script,scene_plan}(state, {...}) to "validate and persist." No function with any of those names (or a close variant) exists anywhere in the repo (grep -rn "def handle_" across all .py files returns zero matches). This is localized to these 3 files — all 12 pipelines' other director docs, including explainer's own asset-director.md/edit-director.md/compose-director.md/publish-director.md/proposal-director.md/research-director.md, correctly describe the real, implemented, tested mechanism (lib/checkpoint.py::write_checkpoint() + validate_artifact()).
2. Scene Types table conflates two incompatible vocabularies
scene-director.md's "Scene Types and When to Use Them" table (lines 66-87) lists 16 names under a Type header, implying they're valid values for a scene's type field. But schemas/artifacts/scene_plan.schema.json's actual type enum has only 9 values (talking_head, broll, animation, character_scene, diagram, text_card, transition, generated, screen_recording). The other 9 table entries (hero_title, stat_card, bar_chart, line_chart, pie_chart, kpi_grid, comparison, callout, progress_bar) aren't valid schema values at all — confirmed empirically: constructing a scene with "type": "stat_card" and validating it raises a jsonschema.ValidationError.
Root cause: those 9 names are actually the downstream cut.type vocabulary consumed later by the Edit stage / video_compose.py / remotion-composer/SCENE_TYPES.md — a real, valid, different vocabulary — presented in this table as if it belonged to the Scene Planner's own artifact. This conflation exists only in explainer; none of the other 11 pipelines' scene-director.md files have this pattern.
Proposed fix
- Replace the 3 fictitious calls with the same wording used everywhere else: "Validate the X against the schema and persist via checkpoint."
- Rename the table header to make clear these are render-template names for
cut.type at the Edit stage, add a "Maps to scene.type" column giving each row a deterministic, schema-valid value to actually write.
A PR implementing this (doc-only, verified against the skills-existence/structure contract tests) will follow.
Summary
Two independent documentation defects in
skills/pipelines/explainer/:1. Fictitious submit function (3 files)
idea-director.md:132,script-director.md:210, andscene-director.md:229each tell the agent to callhandle_explainer_{idea,script,scene_plan}(state, {...})to "validate and persist." No function with any of those names (or a close variant) exists anywhere in the repo (grep -rn "def handle_"across all.pyfiles returns zero matches). This is localized to these 3 files — all 12 pipelines' other director docs, including explainer's ownasset-director.md/edit-director.md/compose-director.md/publish-director.md/proposal-director.md/research-director.md, correctly describe the real, implemented, tested mechanism (lib/checkpoint.py::write_checkpoint()+validate_artifact()).2. Scene Types table conflates two incompatible vocabularies
scene-director.md's "Scene Types and When to Use Them" table (lines 66-87) lists 16 names under aTypeheader, implying they're valid values for a scene'stypefield. Butschemas/artifacts/scene_plan.schema.json's actualtypeenum has only 9 values (talking_head, broll, animation, character_scene, diagram, text_card, transition, generated, screen_recording). The other 9 table entries (hero_title, stat_card, bar_chart, line_chart, pie_chart, kpi_grid, comparison, callout, progress_bar) aren't valid schema values at all — confirmed empirically: constructing a scene with"type": "stat_card"and validating it raises ajsonschema.ValidationError.Root cause: those 9 names are actually the downstream
cut.typevocabulary consumed later by the Edit stage /video_compose.py/remotion-composer/SCENE_TYPES.md— a real, valid, different vocabulary — presented in this table as if it belonged to the Scene Planner's own artifact. This conflation exists only inexplainer; none of the other 11 pipelines'scene-director.mdfiles have this pattern.Proposed fix
cut.typeat the Edit stage, add a "Maps toscene.type" column giving each row a deterministic, schema-valid value to actually write.A PR implementing this (doc-only, verified against the skills-existence/structure contract tests) will follow.