video/skills/pipelines/screen-demo/edit-director.md

Edit Director - Screen Demo Pipeline

When To Use

This stage turns the plan into a concrete, schema-valid edit: trims, speeds, overlays, subtitles, and transitions. Keep the edit simple enough to execute with the current tooling and explicit enough that composition is predictable.

Prerequisites

Layer	Resource	Purpose
Schema	schemas/artifacts/edit_decisions.schema.json	Artifact validation
Prior artifacts	state.artifacts["assets"]["asset_manifest"], state.artifacts["scene_plan"]["scene_plan"], state.artifacts["script"]["script"]	Assets, visual plan, timing
Playbook	Active style playbook	Overlay and pacing rules

Process

1. Start With The Smallest Clear Edit

Screen demos get worse when over-edited. Build the timeline in this order:

1. trim or cut dead time,
2. apply speed changes,
3. place overlays,
4. set subtitle behavior,
5. define audio behavior,
6. capture detailed crop/ramp notes in edit_decisions.metadata.

2. Keep The Schema Clean

Use cuts[] for actual source segments and speed changes. Use overlays[], subtitles, music, and transitions only for things the schema already models. Put screen-demo-specific detail in metadata:

• crop_keyframes
• speed_plan
• subtitle_position_overrides
• audio_notes
• variant_notes

3. Editing Rules

• the viewer should see useful motion or result within the first seconds,
• result moments stay at normal speed,
• typing, installs, and waiting should be accelerated or removed,
• no cut starts mid-word or ends before the payoff lands,
• do not introduce more motion through editing than the scene plan asked for.

4. Overlay Rules

• hook or step label can appear immediately,
• callouts should appear slightly before the action,
• blur masks must be treated as critical, not optional,
• subtitles and callouts must not compete for the same space.

5. Audio Rules

• keep primary speech clear and centered,
• mute or greatly reduce meaningless sped-up noise,
• only use background music if it adds value and survives ducking gracefully,
• if narration was generated, ensure it fits the tightened timeline.

6. Quality Gate

Timeline integrity:

• Cuts cover the full intended timeline
• No accidental black gaps
• Speed ramps don't overlap
• Effective duration matches the brief closely

Overlay integrity:

• Every planned callout or mask is represented
• No overlay collisions
• UI-anchored overlays are documented clearly enough to position during compose

Audio integrity:

• Primary audio or narration covers the entire timeline
• Speed-up segments have intentional audio treatment
• Music, if present, will not compete with instruction

Subtitle integrity:

• Subtitles are present for all narrated sections
• Position overrides protect important UI content
• Subtitle timing still works after planned speed changes

Common Pitfalls

• Overbuilding the edit with cinematic transitions the workflow does not need.
• Letting sped-up audio become a wall of harsh clicks and typing.
• Forgetting that crop and speed plans live in metadata, not arbitrary schema fields.