hybrid-explainer

name	hybrid-explainer
description	Operate the Hybrid Explainer Factory CLI (research/script/scene/asset/render pipeline for the Boardroom Autopsy channel and future channels) without bypassing its approval gates or touching the ledger by hand. Use whenever asked to create, research, script, plan, produce, render, or ship an explainer video project in this repo.

Hybrid Explainer Factory — Operator Skill

This is a local-first CLI application (explainer ...), not a service you call over HTTP. Every command below is a real Bash invocation of that CLI.

Rules (non-negotiable)

1. Read the project's current status before acting: explainer status <slug> (or inspect projects/<slug>/project.json directly). Never guess what stage a project is in.
2. Read the channel profile before writing research/script/image prompts: config/channels/<channel>.yaml — its forbidden_style list and style_key_image/style_bible fields are hard constraints, not suggestions.
3. Use the existing project files before generating new ones — check projects/<slug>/research/, script/, scenes/ before re-researching or re-writing something that already exists.
4. Never submit a paid generation job (explainer production start) without production-plan approval (explainer production approve) already recorded.
5. Never render the final video (explainer final render) without animatic approval (explainer animatic approve) already recorded.
6. Never edit ledger.json, jobs.jsonl, or audit.jsonl by hand — they are append-only records written exclusively by the application's own services. If a number looks wrong, that's a bug to fix in the code, not a file to patch.
7. Use explainer CLI commands for every state transition — never write to project.json's status field directly, even for a "quick fix". The state machine (explainer.models.project.ALLOWED_TRANSITIONS) exists specifically to make that impossible by accident; don't defeat it on purpose.
8. Failed jobs stay in the ledger — never delete a failed GenerationJob or LedgerEntry to "clean up" a cost report. The failure is the record of what was tried and what it would have cost.
9. Prefer scene-level fixes over restarting a project: explainer scene retry <slug> <scene_id> or explainer scenes reroute <slug> <scene_id> --visual-type <type> instead of re-running the whole pipeline from scratch.
10. Report blockers plainly. If explainer doctor shows a MISSING dependency, or a project is BLOCKED, say so directly and name the exact failing scene/check — don't paper over it with a workaround the operator didn't ask for.
11. Never let voice generation, scene planning, or asset generation begin without explainer script approve (Gate 1) already recorded — the same non-negotiable pattern as the production-approval and animatic-approval gates above.

Command reference

See README.md in this repo for the full command table (added in Phase 6 Task 10) — it is the single source of truth for exact CLI syntax, kept in sync with the actual explainer/cli.py. Do not duplicate that table here; read it before running an unfamiliar command.

When research/script/image-prompt work is needed

prompts/researcher.md, prompts/scriptwriter.md, prompts/image-prompt-writer.md, and prompts/motion-prompt-writer.md (all added in Phase 2) are the actual instructions for that creative work — read the relevant one before writing research claims, a script, or an image/motion prompt for this project. This skill tells you when to do that work and how to gate it through the CLI; those prompt files tell you how to write the content itself.