| name | shot-brief-writer |
| description | Convert video-composer decisions into precise shot briefs for sub-agents or sub-nodes. Use when a section needs a self-contained spec containing global style, transcript excerpt, neighboring shots, dependencies, asset requirements, presenter/content layout, and expected output. |
Shot Brief Writer
Overview
Write the handoff packet that a specialist node needs to execute a shot without breaking global consistency.
Inputs
global-style-spec.json- composer shot entry
- transcript excerpt and timing
- previous and next shot summaries
- selected specialist type
- dependency constraints
Rules
- Include the global style spec or a direct path to it in every brief.
- Include neighboring shot summaries so transitions and continuity are not invented in isolation.
- Include timing source and cue confidence. Mark rough-script or duration-scaled timestamps as provisional.
- Include named presenter dock rectangles and reserved content rectangles whenever presenter and content share the canvas.
- Include a layout decision before asset instructions: content inventory, chosen template, rejected alternatives, safe zones, minimum readable sizes, and why the template is hard to break.
- Include a creator effect contract whenever a shot or transition uses creator-style motion, caption emphasis, generated inserts, overlays, audio cues, or precomposition.
- For every elevated/depth beat (3D surface, camera move, kinetic type, section device), include a renderable contract: the exact registry capability id, its real slots / content-kinds / caps (from the catalog digest), the asset it binds to and that asset's kind (e.g. hero-slab/surface needs video, not a still), and a declared flat fallback the composer drops to if the asset or kind is missing — so the beat can never degrade silently into an empty slab, a dumped gap-notice, or overflowed text.
- For every elevated beat also name the concrete reference move it is based on and its source (see
/render-lab-design-system "Elevated-beat moves") — design grounded in real technique, not invented.
- LOCKED — voice-guided timeline. On the voiced path a beat's on-screen duration = its spoken cue span (breath-to-breath). NEVER write a brief that asks for a beat to outlast its narration via
visualBudgetSeconds — that field is INERT on the voiced path and a budget > spoken value is the BANNED budget-stretch that desyncs the continuous audio track and is gate-rejected (pipeline/qc-voice-sync.mjs). To hold a beat longer, the brief requests a LONGER NARRATION for that beat (a script change), never a decoupled visual budget. (The audio-reconciled exception is not implemented on the continuous-WAV path.)
- For every beat that has both narration and on-screen text, include a required content-split — three short lines stating how the voice and the slide divide the work, per
/narration-slide-division (don't restate its rules):
slide carries: the nouns/number/turn-word on screenvoice carries: the motivation/mechanism/bridge — the why the slide can't showoverlap allowed: brand | cta | keyword:"…" | none
Example: slide carries: "−38%" (DeltaBars) · voice carries: how routing picks the cheaper path each time · overlap allowed: none.
- State what the shot must accomplish, not just what it should show.
- State output file path, format, duration, fps, and whether alpha is required.
- State dependencies and whether the job can run in parallel.
- Avoid asking the specialist to reinterpret the whole video unless that is its job.
Creator effect contracts must state: purpose, owner (Remotion, Hyperframes, generated, or precompose), effect type, cue source and window, safe zones, audio budget, caption budget, fallback, and QC targets.
Output
Write one shot-<id>-brief.md or equivalent JSON block per shot/job. See references/shot-brief-template.md.
