--- name: iterate-video-script description: Revise an existing Video Studio script from passage comments or explicit feedback. Use for script iterations, applying script review notes, or working on a script marked Needs editing. For new drafts use face-camera-recording-script. For feedback on rendered video use iterate-video-edit. --- # Iterate Video Script Apply script feedback to a new Studio revision while preserving unrelated copy. ## Contract Checklist - Use the current script as the baseline. Preserve prior versions and comments. - Keep each change tied to feedback or a necessary adjacent edit. - Explain why the revision was needed, grounded in feedback and the prior draft, so the lesson can guide future scripts. - Verify the saved text, beats, rationale, and addressed comment links before handing the revision back for review. ## Workflow 1. Select the video and read its current script, revision, beats, and comments with `read_script`. - If the user asks for the next script, find an accessible script marked Needs editing. Choose the one waiting longest when reliable timestamps are available. Disclose any fallback and report when none is ready. - Use `list_script_versions` and `read_script_version` for feedback on or references to an older version. Apply it to the current script only where it still fits. - Anti-patterns: guessing the video, using an older draft as the baseline, treating comment presence as readiness. 2. Make the smallest revision that addresses the feedback. - Read the [channel editorial guidance](../face-camera-recording-script/references/channel-editorial-guidance.md) and [narrative checklist](../face-camera-recording-script/references/video-narrative-checklist.md). Use them within the requested scope. Ask only if a material conflict or ambiguity prevents a faithful revision. - Preserve unaffected passages. Update story beat anchors when their opening quotes change. - Anti-patterns: rewriting for taste, silently applying stale feedback, broadening the revision to fix unrelated issues. 3. Compare and save. - Compare against the baseline and account for every substantive change. Use `revise_script` with the current revision, exact quoted passage replacements, affected beats, and a concise rationale. An optional message summarizes the change. Include fully addressed comments by their original version and comment IDs, with a brief description of each fix. Save separate revisions when fixes are ready at different times. Write each beat as one short story sentence, using a natural conjunction where it connects to the preceding beat; keep editorial rationale and production directions out of beats. Verify its opening quote against the revised script. On conflict, reread and reconcile before retrying. - The rationale appears as AI interpretation: identify the specific weakness or unmet requirement in the prior draft, explain its effect on the audience or factual reliability, and explain why the chosen approach addresses it. End with a concrete principle that would prevent the same problem in a future draft. Scale the explanation to the change; do not turn it into a list of edits or speculate about the author's motives. - Ground the interpretation in the actual feedback and text. Distinguish a stated preference from an inferred cause, preserve user feedback verbatim, and do not claim an improvement is proven or approved before review. Use the same standard when adding rationale with `annotate_script_version`; preserve existing historical notes unless asked to revise them. - If the action is missing, use Find Missing Tools. Use the Studio editor only if it can preserve revision history and the exact target can be verified. - Anti-patterns: overwriting concurrent work, replacing a saved version, recreating the video, substituting a change log for a rationale, inventing causes or retrospective approval. 4. Verify the revision and resolve addressed comments. - Read the spoken copy as a viewer would hear it. Cut defensive caveats and fold essential assumptions into the line where they matter. - Verify the requested fixes, unchanged passages, resolved beat anchors, and saved rationale. Check that the rationale explains the diagnosed problem and prevention principle rather than merely summarizing edits. Read back the revision and original comments to confirm the links and resolution. If the connected tool exposes only the older full-text input, preserve the untouched text exactly and resolve fully addressed comments with `set_script_comment_resolved` after verification. Leave partial or unresolved feedback open and keep the script ready for review. - Anti-patterns: leaving addressed feedback open, resolving partial fixes, approving or advancing production without a request, claiming success from the write response alone. ## Anti-Patterns - Treating a script iteration as permission to change the video edit or publishing material. ## Output Link the saved script and report the revision, comments resolved, review status, and any unresolved items. Validate workflow changes against [revision rationale checks](tests/scenarios.md).