skills/film-edit/references/JOIN-REPAIR.md

# Improving a join between existing clips

Use when the user asks to improve how A connects to B. This is diagnosis and
editing first, not an automatic transition, extension or regeneration workflow.

## Inspect and name the failure

Resolve the exact source versions and current trim windows. Play the join with
sound and enough surrounding action to understand the exchange, then inspect
actual outgoing/incoming frames around the cut. Use available frame inspection
tools; a thumbnail or room map alone is not evidence of what the clips do.
Check movement phase/direction, positions, eyelines, framing, props, dialogue,
room tone and emotional continuity. State what was observed, including source
times, and distinguish it from a hypothesis. If playback or frame access is
unavailable, disclose what remains unchecked rather than guessing.

If there is black, a freeze, flashing or repeated frames, check whether it exists
in the source/join or only in the review player before modifying footage.

Explain the problem in plain language: duplicate action, a bad cut point, an
audio interruption, incompatible staging, or missing story information. Someone
appearing without an established arrival is not the same problem as a repeated
frame. An intentional abrupt cut is not automatically a defect.

## Recommend the smallest relevant repair

Consider these in increasing scope, but offer only options supported by the
inspection. Do not spend time trying every technique in sequence.

| Observed problem | Candidate and limit |
|---|---|
| Overlap, dead time or a poorly placed cut | Trim or move the cut; preserve complete words and required action. |
| Audio gap or an abrupt response | J/L cut existing audio when speaker visibility, lip-sync and meaning allow; do not duplicate or invent dialogue. A bed cannot fix a changed voice. |
| A distracting visible discontinuity | Crop/reframe only if the source has enough resolution and the required subject/action remains visible. It cannot establish an unseen arrival. |
| A missing cause, arrival, reaction or response | Reuse existing coverage if it supplies the beat; otherwise propose a new connecting shot with a clear story purpose. |
| Existing footage cannot support the chosen connection | Targeted edit or regeneration of the affected material, explaining what approved content would be at risk. |

Do not use a dissolve, zoom or fade as a generic cure for inconsistent positions.
Honor an explicit choice such as “crop only”; explain if it cannot solve the
observed issue. Diagnosis alone does not authorize a repair or credit spend.

## Design a connecting beat before choosing inputs

Record a compact join note alongside the affected shot cards/prompt versions:
the source versions and windows, observed issue, chosen repair, what must remain
unchanged, and the outgoing → connecting → incoming story beats. This is an
editing decision, not another approval widget or a new full-film planning pass.

For a new insert, define both boundaries: where people are, what they look at,
what moves, how the emotion carries, the exact line and its speaker/addressee,
and the action or response that motivates the next cut. Establish an arrival
before showing the arriving character answering. For example: an approaching
person is noticed → the other character reacts and speaks → cut to the answer.
Do not replace approved speech with silence to simplify voice matching.

Then choose inputs for that action. An outgoing frame or motion excerpt is useful
when continuing a specific pose, state or movement; it is not compulsory for
every camera change. For a new angle, anchor the geography and that angle's
composition, plus the characters' identity/wardrobe references. Reuse an unchanged
room map. Create a new still only if essential staging is not established by
existing references. Follow the selected model's live schema and the existing
reference/input gates; never assume an extend model accepts images.

A new insert is distinct from extending A or regenerating B. Explain the selected
operation; do not silently substitute one for another. A bridge introduces TWO
joins to verify and is not guaranteed seamless. Run the prompt-verify step in
`../../film-scenes/references/PROMPT-VERIFY.md` before any generation — an edit
or extend call has its own row in its governing-files table, and a repair is a
new dispatch with new arguments, never an approved prompt repeated. Quote the
actual dispatch and obtain the required credit approval; reuse an already approved
creative direction without asking the same questions again.

## Compare without replacing the accepted cut

Keep original URLs, trims and the accepted timeline intact. Store candidates
separately with their source versions, operation and prompt/edit settings. Inspect
both joins with sound and boundary frames, and report remaining weaknesses.

Show the original A → B and the candidate A → B (or A → insert → B) as focused
review sequences with enough lead-in/out to judge pacing. This is an explicit
exception to the whole-film-only review rule. Use the existing review tool's
supported fields, not invented comparison modes: switch between labelled preview
sequences on one active board, or, when the user wants both together, use one
clearly labelled comparison timeline with distinct clip IDs per variant. Such a
timeline is a comparison reel, never the movie; its feedback must not overwrite
the accepted film's cut. Do not show only the isolated bridge.

After the user chooses, apply that candidate to the movie and check the full-cut
context. Keep the previous cut recoverable. A rejected candidate never becomes
the select. Do not run an automatic chain of paid attempts: after rejection,
explain what failed and propose a materially different correction with its quote;
without a defensible next step, stop and retain the original.