Skip to content

explainer pipeline docs: fictitious submit function + scene-type/schema vocabulary conflation #417

Description

@Alan5168

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

  1. Replace the 3 fictitious calls with the same wording used everywhere else: "Validate the X against the schema and persist via checkpoint."
  2. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions