editor-plan-and-check

Editor Plan And Check

Requires

A running Scrollmark editor whose commands you can call: the SocialGPT editor chat, or scrollmark mcp from @scrollmark/cli for a coding agent. Without it, the brief-first, plan-once, check-once discipline still applies to editing in any tool.

Aim for three rounds: gather, plan, check. Every extra plan costs the user a round and an extra undo step.

1. Pin down the brief

Settle these from the request and timeline_describe before writing anything:

What changes, and what stays. Keep the user's own clips, text they wrote and edits they made unless they asked to change them.
Platform. One they named, else the editor's safe zone, else generic. The canvas size is fixed; you cannot change the aspect ratio.
Length. A number they gave. Without one, keep the strongest complete takes; do not cut to a length nobody asked for.
Look. Caption kit from the editor-captions skill. Keep the existing look unless they asked for a new one.

Use a sensible default for anything unsaid, and name the defaults you chose in your reply. Ask only when the edit cannot be made without the answer.

2. Gather in one round

Call everything the plan needs together: timeline_describe (transcript: "words" only when cutting or timing on words), footage_proposeKeepRanges for a recut, media_searchCatalog for stock (not for a music bed: the music op searches itself), the skills that guide the writes, and the tool groups you will need. Search once per item and pick from its results. Do not read what you will not use, and do not write anything (including imports) before the plan.

3. Choose every value before writing

Captions: a captions.applyRhythm op, then a captions.applyPreset op with kitId, size, placement and platform, in the same plan, as editor-captions says. Do not leave sizing for a second plan.
Overlays: start time from describe's words, a duration, and a position inside the safe area.
Order: cuts first (keepRanges or timeline.applySourceRanges), then captions (they follow the cut), then overlays and audio.

4. Apply one plan

Put every change in one timeline_applyPlan. Name what an op creates with "as": "$name" and use that name in later ops. When there is a target platform, pass it as the plan's platform so its lint checks that platform's safe area.

5. Check once

Checking is read-only; fixes go in one follow-up plan.

Read the result first (no tool call). lint: text outside the safe area or clipped; each finding names the clips. added / changed / removed: do they match what you meant? A recut that removed every clip, or captions that never appeared, is wrong.
Look only when it matters. After placing captions, titles or overlays, the result carries frames where you placed or changed them, with the elements that overlap. Look at those. Call preview_inspectFrames (1–3 timeline seconds) only when the result has no frames and you placed text, or to see a moment the frames did not cover.
Check for: text over text or over a face; captions missing from part of the cut, or not matching the speech; a title on screen too briefly to read (under about 1.5 s); music louder than speech (duck it to volumePercent 15–25); empty or black frames at the start or end; a length that misses the brief.
The lint covers the safe area named in the result's platform. Run qc_run only when the result has no platform (an older editor) and there is a target platform.

6. Fix once, then answer

Write one follow-up plan against the result's stateToken, using handles from the result (including track handles such as t2). Describe again only to touch clips the result did not list. For safe-area findings, qc_applyFix with allSafe: true is fine.

If the plan failed because something outside the edit failed (a stock download, a provider error), nothing was applied. Send the plan once more without that item and the ops that used it, then tell the user what you left out and why. Do not drop the whole edit for one missing download.

Make at most one fix pass, and do not inspect frames again after it: its result's lint is the check. If something is still off, tell the user what it is instead of looping.

Then say what changed and the defaults you chose. Mention undo only when you deleted something, made a large change, or the user is unhappy.