---
name: shot-design
description: Design or revise shots for a historical-drama Scene. Use when choosing framing, camera position, composition, blocking, action, expression, camera movement, dialogue coverage, duration, or shot entry and exit state.
---

# Shot Design

Express an approved Scene through minimal necessary, narratively motivated, continuous, provider-agnostic coverage. Plan the group before individual Shots; every Shot must declare Narrative Input State, Required Transition, and Narrative Output State in addition to visual entry/exit state. Do not redesign the Scene or produce media.

For a single Shot's dialogue timing request, follow the [Dialogue Timing contract](../../docs/dialogue-timing-contract.md). Resolve the existing binding array in order, canonical speakers and estimates, and each line's DPD; use `dialogue_timing_context()` to obtain the complete adjacent-turn context. Form a transient `TransitionIntent` for each turn, pin it to that context fingerprint, and explain the combined dramatic action, objective, tactic, relationship/authority, activation/control and continuity/change basis. Choose only opening, immediate response, short reaction, or deliberate reaction; explicitly required simultaneous speech uses the unsupported overlap intent. Immediate response means the preceding line has finished; a literal interruption while it continues is overlap. Do not classify emotions or assign milliseconds. Call `plan_dialogue_timing()` to apply the deterministic platform policy and retain the plan in Agent state. Missing estimates require an upstream planning estimate; a conflict reports the minimum required Shot duration for upstream review. On changed input, review the semantics again rather than simply replacing an old intent's fingerprint. For timing-only requests, stop after the plan/diagnostics and review, before the creative persistence steps below. Planned windows are separate artifacts, never Shot binding fields, observed mouth timing, accepted AV placement, or authority to generate/mux media.

## Creative Lifecycle

### 1. Understand Goal

Clarify whether the request creates new Shot coverage or revises existing Shots, the parent Scene and exact coverage scope, the requested visual outcome, and explicit format, duration, continuity, stable-reference, or production constraints. Identify what the camera must express about the Scene turn. Do not equate one sentence or dialogue line with one Shot automatically.

### 2. Gather Context

Assess context sufficiency before planning. Continue when the approved Scene's assigned historical beats, Narrative Input/Output State, Required Transition, purpose/action/turn, canonical `spokenContent`, spatial layout, blocking, time/environment, neighboring Shot states, and production constraints are supplied. Use `scene.get_scene` for the stable parent and `shot.get_shot` for a known `shotId`. With a known `sceneId`, use `shot.list_shots` for structural enumeration and neighboring continuity; when only a natural-language identity is known, use `shot.search_shots` scoped to the Scene when possible and judge candidates.

Use `asset.get_asset` or `media.get_media` only when a selected stable reference is needed to judge character, location, prop, wardrobe, or visual continuity. Use `context.build_context` only when required parent or existing Shot context was not supplied. Consume approved historical context rather than repeating research per Shot. If a consequential historical issue is unresolved, formulate a focused question and stop before planning or persistence so the Agent or Host can choose an existing research capability. If Scene intent, required references, spatial state, or continuity cannot be obtained or conflicts, state the blocker and do not draft or persist.

### 3. Plan

For a supplied screenplay intent handoff, apply [Cinematic Intent translation and preservation](../cinematic-screenplay-incubation/references/cinematic-intent.md). Project relevant intent from the scene set to this coverage group, retaining source, priority, POV relation and boundary obligations. Translate meaning into concrete action/composition/continuity; MUST constrains meaning, SHOULD allows a justified alternative, FREE may be discarded. Keep the full assigned-intent list for group review even when individual shots receive smaller selections.

Before drafting, read [Professional Shot Planning](references/planning.md) and the [Dialogue Layer content convention](../../docs/dialogue-layer-content-convention.md), then apply them. Create an internal coverage plan that inherits rather than repairs the Scene; define required historical/story observations, coverage strategy, Shot economy, and for each retained Shot its narrative purpose, `narrativeInputState`, `requiredTransition`, `narrativeOutputState`, subject/action/blocking, camera language, rhythm, positive integer `plannedDurationMs`, visual entry/exit state, continuity, references, and feasibility. When spoken content exists, decide which Shots bind each item and why as `ON_SCREEN_SPEAKER`, `REACTION`, `OFF_SCREEN`, or `VOICE_OVER`; do not copy or rewrite its text. Keep it in Agent Run Context or temporary working state. Do not call `shot.create_shot` or `shot.save_shot` to store it.

### 4. Execute Draft

Execute the strategy as complete candidate formal Shot states that together cover the Scene turn with the fewest necessary Shots. Each Shot persists `plannedDurationMs`; a Shot carrying speech persists only `spokenContentBindings[]` objects with `spokenContentId` and `coverageIntent`. A Scene item may bind across speaker and reaction Shots without duplication and remains one future audio item. Make camera choices serve information, performance, spatial relation, emotion, action, or continuity; preserve screen direction, axis/eyeline, positions, action phase, performance energy, assets, props, costume, time, lighting, and ongoing motion. Simplify, split, or redesign an overloaded Shot until its action, space, movement, references, spoken load, and entry/exit states are executable downstream. The draft must not contain copied dialogue/narration text, audio timing, one-line-one-shot splitting, redundant coverage, camera labels without subject/action, test content, or scratchpad. Do not persist partial Shot drafts.

### 5. Review

When an intent handoff exists, add an Intent Preservation Matrix against actual shot IDs and sequence: PASS, ACCEPTABLE_INTERPRETATION, INTENT_LOSS, CONFLICT or N/A. Missing MUST or a conflicting interpretation blocks the group. FREE omission does not; a SHOULD alternative is judged by preserved purpose. Check the first/last effective perception and subjective-to-objective return, not just item presence. Keep user cinematic acceptance separate from record validation.

Before any write, read [Shot Review and Revision](references/review.md) and apply the entire coverage rubric. Critical checks are reported as `CHARACTER_VISUAL_CONTINUITY`, `COSTUME_PERIOD_CONTINUITY`, `PROP_STATE_CONTINUITY`, `SHOT_ACTION_CONTINUITY`, `SCENE_STATE_CONTINUITY`, `CAUSAL_NARRATIVE_CONTINUITY`, `HISTORICAL_BEAT_COVERAGE`, `FULL_STORY_ARC`, and `DURATION_FEASIBILITY` separately. Validate every binding against the parent Scene, coverage intent, absence of copied body/timing, and numeric duration. Deduplicate an item shared across a contiguous coverage group; its estimated duration must fit the group's total planned duration with playable room for action, reaction, and silence. If `Previous Narrative Output State → Current Narrative Input State` fails or an indispensable action/state is skipped, return `FAIL_NARRATIVE_TRANSITION` even when visual checks pass. Unmotivated or redundant coverage, unresolved narrative continuity, unproducible complexity, spoken overload, or failure to cover the Scene turn is critical. Mark Review PASS only when every gate passes; otherwise mark Review FAIL.

### 6. Revise or Re-plan

If screenplay and intent are correct, an intent-loss finding belongs to SHOT_PLANNING. Declare affected shots and continuity neighbors, preserve unrelated shots and all upstream text, and use at most two targeted rounds with complete-group review after each. An upstream ambiguity goes to its actual owner. A standalone requested Shot Plan can remain a reviewed local artifact without Domain writes or media production.

On Review FAIL, do not persist. Follow [Shot Review and Revision](references/review.md): Locally revise one framing, angle, movement, planned duration, binding, composition, or minor continuity defect. Resolve spoken-duration conflict through reviewed coverage changes, extending/splitting Shots, reaction coverage, or an upstream Scene revision of non-`mustKeep` content; never let this Skill or a Provider silently rewrite the Scene source. Re-plan the current Shot group when coverage strategy, economy, spatial/axis logic, Scene-turn coverage, or generation feasibility fails. If the Scene lacks playable conflict/action/state change, label an upstream Scene issue instead of hiding it with camera technique. After any revision or re-plan, review the complete coverage again. A fix never goes directly to persistence without Review Again and PASS.

### 7. Persist

No Review PASS means no create or save. Persist only when required context is sufficient, the plan and complete draft coverage exist, all critical checks pass, and the design is minimal necessary, narratively motivated, continuous, and production-ready without unresolved Scene/reference conflict. One-line-one-shot splitting, repeated coverage, missing narrative purpose or subject/action, spatial/action discontinuity, asset drift, or unproducible complexity cannot pass. Plan, draft reasoning, rejected alternatives, review notes, and revision notes remain Agent Run Context or temporary working state; do not put them in Shot `content`. Persist only reviewed formal Shot results.

Use `shot.create_shot` only for a genuinely new Shot after producing the complete initial formal state needed by this Skill. A successful create is the normal first write and returns the stable ID; do not call `shot.save_shot` immediately afterward unless a concrete revision has actually occurred. Use `shot.save_shot` only to revise an already persisted Shot because of a specific request, discovered error, upstream change, or necessary addition.

Organize persistence as **Stable Envelope + Domain Content**. Keep the parent Scene ID, string-valued shot number, optional title, and optional shot type in the create envelope; use the stable Shot ID, shot number, title, and type for a revision. Put reviewed narrative purpose, Narrative Input State, Required Transition, Narrative Output State, subject/action/blocking, camera language, continuity dimensions, references, feasibility, positive integer `plannedDurationMs`, canonical `spokenContentBindings`, visual entry/exit state, and other formal Shot facts in the open `content` object. Bindings contain only `spokenContentId` and `coverageIntent`; never persist copied text, Shot-local `spokenContent`, `spokenContentRefs`, audio/subtitle timing, or aliases. These are creative content, not new persistence fields. Do not move the parent Scene ID or hide, duplicate, or rename envelope fields inside `content`. Treat the Tool catalog as the sole machine-schema source. Submit save as a full replacement formal state, never as a patch, scratchpad, stringified JSON, or routine follow-up to create. Use `context.refresh_context` only after a write makes current context stale. Read a stable Asset/Media only when continuity requires it; do not create or resolve assets, produce media, add provider workflow/model parameters, redesign the Scene, or automatically invoke another Skill.