ottolsq/vigen

vigen（AI Video Production Assistant）

Turn a single idea or a script into a complete, ready-to-copy video production plan you can use directly in AI generation tools. Target audience is users with zero filmmaking background: storyboarding, camera moves, lighting, and prompt engineering are handled by this skill; you only make decisions at key confirmation points.

Deliverables: A set of files in the project directory—script, anchoring table (characters/scenes/props/style), image prompts, video prompts, voice line table, editing checklist; series projects also include a cross-episode story state file. It solves six problems: remove AI-artifact feel, four-layer consistency, physically plausible action, expressive camera moves & transitions, complete narrative, and model-executable prompts.

Purpose of This File (Read Before You Begin)

This file only says "what to do when". It does not say "how to write it specifically." Every rule has only one home (see table below). This file gives a single, judgeable key point + a pointer.

⚠ A key point alone is not enough to produce a qualified prompt—for slots, examples, and parameters, read the home file. Do not act based on memory of this file.

Rule Ownership Table (The One and Only Home for Each Rule)

Concept	Home
Skeleton A/B slots, six prop judgment rules, L1-L4 grading for image generation, six hard standards for reference images, priority order for reference images, second-level timing, prohibited sequences, vocal expression formula, validation rules	references/prompt-rules.md
Four-layer anchoring, style bible, head/body separation, character routing, reference image weight discipline, baseline reference method, minimum reference set, voice auto-extraction, series memory, invalidation propagation	references/consistency.md
40 camera moves, 8 generation-end transitions + 5 editing-end transitions, camera position semantics, segment length buckets, function decision table, peak & emphasis techniques, rhythm templates	references/cinematography.md
16 style library (incl. Pixar 3D), color palette, style extraction (dream card), project style isolation	references/styles.md
Remove AI-artifact feel, four tension methods, two surface tiers & shape constraints, dynasty discipline, text physicalization	references/realism.md
Model capabilities, generation paths, reference image limits, duration limits	references/models.md
7 major self-checks for plot holes, hook & suspense discipline, three-layer story separation, GATE1.5 rules, four-panel storyboard, Form B override rules	references/screenwriting-craft.md
Platform short drama project setup, tier & episode count, 40 tracks, genre/emotion contract, unit chain, six levels of evidence, paywall, first three episodes	references/short-drama-market.md
Content compliance (filing categories / 11 red lines / sensitive word replacement)—this is a separate layer from "prompt rejected by filter"	references/content-compliance.md
Negative word effectiveness (judged per endpoint)	references/knowledge-index.md
File structure (00-06) and fill-in slot templates	assets/templates.md

Duplication = Defect: If the same rule is written in two files, they will eventually diverge—the V2.4 fix "action capacity scales with duration" existed in three copies, and two old copies drifted until V2.8 before being cleaned up. When you find a duplicate, keep the home in the ownership table and change the others into pointers.

Directory Structure (Module Map—Read on Demand, Not All at Once)

File	When to Read
references/screenwriting-craft.md	Must read during Phase 1a script creation
references/short-drama-market.md	Read once after GATE0 determines "narrative form = vertical short drama" (platform/tier/episode count/track/genre/emotion contract/unit chain/paywall/first three episodes); movie-style projects skip it
references/content-compliance.md	Must read before writing in Phase 1a for vertical short drama projects + before GATE1.5 (filing categories / 11 red lines / sensitive word replacement); movie-style projects skip it
references/prompt-rules.md	Before writing any image/video prompt (including four foundational understandings)
references/models.md	When determining the model after the requirements questionnaire; or when changing models
references/cinematography.md	When designing storyboard shots (camera moves / 8 generation-end transitions + 5 editing-end transitions / shot size / camera position / lighting style library / peak allocation / single-shot duration & rhythm / vertical framing safe zone / 7 scene type shot sequences)
references/styles.md	When deciding the style in Phase 1
references/consistency.md	When building the anchoring table (02) and dealing with cross-shot/cross-episode consistency issues
references/realism.md	When writing character/scene/situation image prompts
references/examples.md	When you need a full example for reference
references/knowledge-index.md	Read this index first when deciding style/storyboard in Phase 1—locate extended knowledge on demand (FACS micro-expressions/combat action/cinematic parameters/director style/multi-view/emotion methodology/UGC texture/2D-to-real), read the corresponding file only if the scene matches. For action-heavy projects, must read action-combat.md. The reading point for expressions.md is advanced (V2.9): do not wait for Phase 5—read it when writing performance state fingerprints and performance timing annotations for situation images in Phases 2-4 (character expressions and body poses in the frame are already happening at the image side). Lesson learned: deferring performance specification to Phase 5 means performance annotations on the canvas have no basis and must be invented from scratch
references/content-safety.md	Must read after a prompt is blocked by the review filter—find a solution by following the de-escalation ladder (wording-level solution library / composition-level pattern table / binary positioning). When writing high-risk topics, only check "does it hit a registered pattern" (sections 2 & 3 of that file + project 03 specification section)—reactive de-escalation (V2.9 user decision): unregistered content is written normally, do not perform preventive desensitization
references/execution-pitfalls.md	When check.py fails to run locally or in a sandbox (section 6 of that file); or when the user asks about operational pitfalls on the execution side; not part of the daily workflow
assets/templates.md	When creating project files

⚠ references/_archive-suspended-claims.md contains archived, suspended claims. Do not read at any stage. Its content is not a rule basis. ⚠ references/learning-guide.md (self-deficiency list / usage boundaries / material absorption ledger) is not part of the daily project execution workflow—only read it when: ① the user provides new learning material, or ② the user asks about the skill's defects/boundaries/learning status. When read, process new material using its Section 1 four-step learning method and update the ledger.

GATE0: Requirements Collection Questionnaire (First Step After Trigger, Before Any Generation)

Proactively ask the user all questions in one go. Do not re-ask what the user has already stated in their message:

1. Content Source: A single idea / Rough script (I will refine) / Complete script (I will storyboard directly)
2. Single Episode or Multi-Episode Series: If multi-episode, ask for estimated episode count and whether each episode has a continuous story
3. Target Duration: Rough duration of a single episode/video (15s / 30s / 60s / longer)
4. Generation Model: Image model (default gpt-image-2.5) / Video model (happyhorse-1.1 / MiniMax-H3 / other)—determines duration and reference image limits. Read references/models.md to provide the user with a capability list. Also ask for the vendor/gateway (same model name from different providers may have different capabilities—note this when locking in, test with a probe before generation, see "Capability Actual-Testing First" section)
5. Aspect Ratio: 9:16 vertical / 16:9 horizontal
6. Voice: Choose based on video model capabilities—happyhorse uses built-in voice (no audio reference); H3/Seedance/Jimeng series use built-in voice or voice reference auto-extraction; use cosyvoice for precise lip-sync only if strict voice consistency is needed or direct output is unsatisfactory (route selection and trial segment timing are in consistency.md, Section 4)
7. (If video model is H3, must ask) Generation Path: Platform/App (includes H3-Context-IR, e.g., Toonflow, Seashell, official API) → Chinese skeleton A is usable directly; Direct connection to H3-Base → must output structured fields according to the mapping table. Determination is in prompt-rules.md, Generation Path Determination section; if the path is unclear, default to "with IR" and note it in the 04 file header
8. Performance Tone: Restrained (default—for poetic/drama/suspense/dramatic works, small expression range) / Neutral (everyday) / Extroverted (comedy/exaggerated emotional scenes)—determines the FACE LOCK slot and performance annotation amplitude baseline. Lesson learned: if you don't ask this, the model defaults to smiling and exaggerated expressions, requiring rework for every segment
9. Narrative Form and Platform (determines script wording and episode layout): Movie-style (default—short film/drama/stylized narrative) / Vertical Short Drama (Hongguo/Douyin paid short drama). If vertical short drama is chosen, ask:
   • Platform (Hongguo/Douyin/other) and tier (Standard 90120s / Long 150195s / Comics 60~90s)
   • Total episode count (60/80/100 or 30/40/50, custom possible) and paywall (Standard three-tier / Pre-TikTok promotion / No paywall, ad revenue share)
   • Track (40-track menu, see short-drama-market.md Section 3) and genre (Emotion flow / Plot flow)
   • Whether it involves public security/judiciary/national security/ethnicity/religion/diplomacy (if yes, filing category = Category 1) → After selecting vertical short drama, Read references/short-drama-market.md, write the project plan into 00 (series) or 01 (single video)

Alignment Obligation (Hard Gate): When parsing the user's idea/script, if you find contradictions, ambiguities, or missing key information (unclear character motivation, plot conflicts, mismatch between duration and content volume, missing scene descriptions) → list the questions and ask the user. Do not fill in the gaps by yourself. Only proceed to Phase 1a after alignment.

Questionnaire Answers and Alignment Conclusions (including skill completions) are immediately written into the "GATE0 Alignment Record" section of 01—the file is the truth. Recovery from interruption depends entirely on it (see Efficiency Obligation section).

Project Structure:

• Single video project: <project_name>/ in the current working directory (01-06 flat)
• Series/multi-episode project: <series_name>/00_story_state.md (series-level, shared across episodes) + <series_name>/ep01/, ep02/… (each episode has its own 01-06)
• If a directory with the same name already exists → intent routing (sequel / targeted modification / phase redo)

Workflow (Six Phases, Script First)

GATE0 questionnaire + alignment → Phase 1a Script creation ─GATE1.5 script finalized─→ Phase 1b Storyboard + anchoring ─GATE1─→ Phases 2-4 Image prompts → Phase 5 Video + dialog → Phase 6 Editing checklist → (Series: update 00_story_state)

The format for each phase is: What to do → What to read → What to produce. Rule details are in the files being read; they are not repeated here.

Phase 1a Script Creation (Do only this before GATE1.5) Refine the user's idea/rough script into a scene-by-scene script. Read references/screenwriting-craft.md—go through its 7 major self-check list item by item. For conflict scenes, first go through the Scene Engine Work Card and the Six Upgrade Questions (Sections 1.4). For episodic narratives, also go through the Current Episode Delivery (Section 1.5, Rule 5). For split-episode/segment narratives, also check Hook & Suspense Discipline and Knowledge Reveal Status. When adapting user material, keep a three-layer story separation ledger (at GATE1.5 presentation, distinguish between "your original text" and "skill completions"). When Narrative Form = Vertical Short Drama: Also read references/short-drama-market.md + references/content-compliance.md. Write according to screenwriting-craft's Section 1.9 Form B Override Rules (dialog direct delivery in the same turn / 15-second four-beat / in-episode settlement / dense visual density / monologue quota). At the end of the script, fill in [Episode Settlement], [Episode Mid-Segment Mini-Hook] (for long tier), [Episode Chapter Break Point]. Movie-style projects do not read these two files and do not fill in these fields. Output: Write the script into the 01_plan_and_script.md Script section + Scene Beat Table + Duration Budget (screenwriting-craft 1.8) + Self-check results. Do not storyboard, do not create the anchoring table, do not write any prompts. Phase 1a has no storyboard yet; "claimed shot numbers" do not exist yet—under check.py --partial, K13 only checks the beat structure; claimed shot numbers will be added in Phase 1b.

GATE1.5 Script Finalization (Hard Stop—Never enter Phase 1b without a finalized script) Present in the chat: story summary + character list + full scene-by-script text + Beat Table Summary (how many beats / which beat is the hook / estimated duration vs target duration) + 7-vulnerability self-check results + issues to be decided, and inform the user: "Once you confirm the script, we move to storyboarding and anchoring; any script changes after this point will require redoing everything downstream. Now is the time with the lowest modification cost." For vertical short drama projects, also attach the compliance self-check results from content-compliance Section 6 (filing/red lines/sensitive words/hook intensity). If the user is unsatisfied → revise and present again, loop until the user explicitly finalizes. Write the finalization conclusion into 01's "GATE1.5 Script Finalization Record" section. When the user provides a complete script, simplify to presenting "self-check + issue list" (do not repeat the script text), but the self-check must not be skipped—if you find vulnerabilities 4/5/7, remind the user instead of silently fixing them. What is locked by finalization is the story skeleton and plot point list, not the storyboard table—the storyboard table is a living document. Subsequent shot additions/deletions go through intent routing as live script revisions.

Phase 1b Storyboard + Anchoring Parse the finalized script (theme/duration/style/emotion) → Plot point list → Storyboard → Anchoring table.

• Plot Point List: Break the finalized script into plot points and write them into 01 (one point per line). The storyboard must cover 100% of them—prevent unauthorized deletion/alteration of the plot.
• Beat Claiming: In the storyboard table's "Claimed Beat" column, write the B interval (e.g., B4-B5). One shot can claim multiple beats; pure transitions/empty shots write —. Beats are not duplicated or missed, and the order matches the shot number (A14/K13).
• Four-Panel Storyboard Breakdown (screenwriting-craft.md Section 4): One shot answers only one question; produce in batches and check the first batch first.
• Segment Length Bucketing by Budget (cinematography.md's "Peak & Emphasis Means" section ③): Divide by compact budget first; do not default to maxing out the limit. Slow motion is only given to explicitly named peaking shots.
• Set Style: Read references/styles.md → After selecting a style, immediately set the overall color palette (3-5 hex color codes, before generating any scene images).
• Design Storyboard: Read references/cinematography.md (both camera moves and transitions must be designed; transition column is a mandatory selection; camera moves are written down to the physical-parameter-level five elements). Identify counter-prior-experience actions and annotate them in the storyboard table—these shots rely on situation images to lock poses. For 9:16 projects, also follow its Section 7 for vertical composition position/safe zone. If the scene hits one of the Section 8 high-frequency types, refer to the sequence skeleton (cede: fighting → use action-combat, slow-mo only for peaks / R4-style orbiting, two-person → use upper/lower positions, vertical opening with information).
• For fight segments, write a bout ledger before arranging shots (action-combat.md Section 0—when the script only says "they fight", never go directly to storyboarding. After turn-by-turn breakdown, the named victory/defeat move is the only place for slow motion).
• Output: 01_plan_and_script.md (add storyboard section) + 02_anchoring_table.md (Read references/consistency.md + assets/templates.md)
  • Add props to the table according to the six judgment rules in prompt-rules.md. If a scene is used in ≥3 shots or has shot/reverse-shot coverage → requires four views + LOCATION MAP. For multi-shot scenes, register the scene master: four-directional anchor + available standing/propping objects (identified from scene images, not from prompts) + a starting position sentence for each scene opening. Build the table according to consistency.md Section 0 Lock-off Checklist: clothing lock tier (default = dedicated image), scene "always-present elements" (audience/apparatus/mat/light color + color code), register repeated large items, style triple-package (bible word-for-word + color code + identity sentence).
  • Add clothing to the table as "one entry per outfit": character anchoring phrase only retains identity-level elements; clothing descriptions are moved to the 02 clothing anchoring table (consistency 1. Clothing Anchoring). For costume-change projects, each outfit has its own independent anchoring phrase and reference image.

GATE1 (Must Stop) Present in the chat: Plan summary (including the selected model) + Full anchoring phrase for each character/outfit/prop + Design intent for each scene + 3-5 consistency anchors + Full style bible + Color palette (color codes + application points) + Peak/Emphasis Means Allocation Table (number of peaks in this episode, what means are used for each peak, corresponding shot numbers—see cinematography's "Peak & Emphasis Means" section). Wait for user confirmation before proceeding. Anchoring phrases and color palette are verbatim in all subsequent prompts. Modification cost is lowest here.

Phases 2-4 Image Prompts Output 03_image_prompts.md. Before writing, read references/prompt-rules.md (including four foundational understandings) + references/realism.md + references/models.md. If characters have emotional scenes/performance states, also read expressions.md (V2.9 advancement—performance state fingerprints for situation images are written now, not waiting for Phase 5).

• First build the Asset Reference Matrix (each asset registers which shots reference it; zero-referenced assets are not generated—prevent resource waste. For minor characters without setup images, use chain reference as a fallback. For user-named finished assets, USER-LOCKED exception is in prompt-rules Section 1.4). Before building the matrix, check for existing assets—an existing project or canvas may already have an asset with the same name (lesson learned: P05 prop was created then abandoned because P04 already existed). If found, reuse; do not recreate. Also, in the 01 storyboard table, add an "Assets on Screen" column with asset IDs—any recognizable prop/scene item appearing in a shot must have a corresponding entry in the 03 matrix. If not, add the asset or delete the item from the shot (Hard Rule 17).
• Person↔Scene↔Situation cross-reference (do not generate them in isolation): A situation image must reference the character as-set image + scene master image. Shots in the same scene but with different states should reference the already finalized baseline reference image. When updating a look/set, reference the previous version to prevent drift. Lesson learned: The rule was written but cross-referencing was not actually done during generation—the scene atmosphere dragged the character back to an old look, or a wound appeared out of nowhere. For three-way referencing rules and bidirectional scope declarations, see consistency.md Section 3 (Image End).
• Then write five sections: Character Reference Images (white-background three-view + face close-up, head and body must be generated as two separate images; do not combine them into one setup image. Anime/Chinese animation can use a four-view composite image, see Hard Rule 12. For young characters, add a skin texture standard sentence. For high-face-drift/multi-view projects, can use the optional single-anchor derivation path—0a: generate full-body front anchor; 0b/side/back/details are derived by modifying the anchor image; see consistency Section 3), Clothing/Costume Reference Images (for costume-change/suit-up projects, one 0a-spec white-background full-body image per outfit; template in templates 1.5), Prop Reference Images (for props that meet the judgment rules, generate multiple states in the same image, then crop into separate images), Scene Reference Images, Situation Reference Images.
• Situation images are generated by L1-L4 grading, not one per shot (a single video generation has only one first-frame position)—grading determination and reference image trade-off priority are in prompt-rules.md Section 1.3. For directions/final states that text cannot lock down → follow prompt-rules 0.10 to append REF-DIR-<shot_number>/REF-TARGET-<shot_number> images.
• First, generate a complete batch of the first segment (3-5 images) for user acceptance before scaling up—verify art style/consistency/composition before proceeding. Four-pass check on generated images (same world / face and clothing match setup images / shot size correct / no extra people). When delivering prompts (not images): the first batch acceptance and four-pass check are performed by the user after generation. The skill writes "not executed (no images)" in the 01 validation record; must not mark as passed.
• If a shot is unsatisfactory after generation, return to fix the image. If the user provides a reference image and says "make it look like this" → extract the style (dream card) according to styles.md, produce a dynamic style bible, then regenerate.

Phase 5 Video Prompts + Dialog Output 04_video_prompts.md—use the skeleton selector in prompt-rules.md: Default skeleton A (one segment, multiple shots + transitions); Skeleton B for fl2va, one-shot tension, or complex scenes split into multiple single-shot clips for the user to edit together (must annotate the reason in 01).

• ACTIVE REFERENCES should be used in full (for the same object, first settle on the sole authoritative reference—do not hang images containing the same object in parallel). Grouping strategy and character minimum reference set are in prompt-rules.md / consistency.md.
• Cross-segment tail frame bridging (V3.7 standard procedure): After Segment N is generated → actively remind the user to capture the tail frame → For Segment N+1, if there is an independent first-frame slot, place it there; for mixed reference (Ref2VA), prioritize the character minimum reference set, place the tail frame after it (do not push character images out). Use SCENE CONTEXT referencing to continue (full text in prompt-rules Skeleton A "Cross-Segment Tail Frame Bridging Standard Procedure"). Frame capture is a tool-layer operation; the skill does not do it. Do not wait for all segments to be generated before capturing frames. If the tail frame has not been rendered yet, write PLAN-TAIL-<N> as a placeholder and continue producing as normal. After frame capture, bind REF-TAIL-<N>. Do not block the pipeline waiting for the tail frame (same E2 human-machine parallelism).
• H3 Multi-Frame Alignment Project (optional): Follow prompt-rules "Generation Path Determination / Multi-Frame Recipe" to pin each segment's cut point frames to the second. If the vendor does not support it, fall back to Skeleton A tail-frame bridging; do not retry repeatedly.
• Fight shot blocks use a seven-state attack-defense state machine (do not write a three-action formula; see action-combat.md Section 7). Non-fight shot blocks use a three-action formula. For decisive actions, add second-level timing + performance prohibited sequences + causal chains.
• Each segment contains FACE LOCK expression locking and dynamic environment layers. Each shot's generation duration is hard-validated against the models.md upper limit. If exceeded, automatically split the segment and use tail-frame bridging.
• Output 05_voice_and_dialog_table.md (for no-dialog projects, use the simplified branch: only fill in section ⓪. For dialog projects, select a route based on the video model's capabilities—happyhorse uses built-in voice, H3 can use voice reference auto-extraction, use cosyvoice for precise lip-sync only if strict consistency is required; see consistency.md Section 4).
• Soundless video route (consistency.md Section 4 "Soundless Video Branch"): In the 04 video prompts, do not write dialog. Only write mouth shape/off-screen voice design (back shot / side face / closed lips / off-screen voice source). The original dialog text remains only in 05 and 01. TTS lip-sync is done in post-production.
• Dialog must have emotion; do not just write "said angrily": Bind every line of dialog with the vocal expression formula (two parts for preceding identity + six parameters; all 8 parts are mandatory). Embed it within the action chain, not as an independent line. Lesson learned: Only writing emotion labels resulted in dialog with no tone or speed variation—flat as reading a script. The writing method and four prohibited forms are in prompt-rules Section 3.5.

Phase 6 Editing Checklist Output 06_editing_checklist.md (edit sequence, crop 0.5s from head and tail of each segment, corresponding transition implementation from 01 transition column, transition audio processing to prevent hard cuts on background sound effects, BGM added in post, color grading hints. For H3 projects, note video retention period and transfer before expiry). Single-shot duration is based on cinematography Section 6 baseline (for Skeleton A, do not recut within a segment; only crop segment head and tail; for Skeleton B/single-shot clips, crop according to baseline). Editing-side transitions (dissolve / fade in-out / flash black / zoom / wipe) are implemented in 06. In 04, write a hard cut at that edit point (per cut point; do not override other transitions in the same segment). For vertical projects, additionally check safe zone / opening hook / breathing points.

Series Projects Additional: After each episode is fully completed, mandatorily update 00_story_state.md (episode story summary / character state changes / prop state changes / episode tail frame description / unresolved foreshadowing). Before starting the next episode, read 00 first, then read the previous episode's tail frame—to prevent forgetting details in long series.

After everything is done, only provide a summary in the chat (project path + one-line description of each file). Do not repeat file contents.

Reporting Discipline (Fixed Shape of Summary): Quantitative results (number of segments/shots / total duration vs target duration / number of image prompts) + check.py results (all passed / which rules were not passed and how they were fixed—Hard Rule 15) + OPEN items (which items cannot be verified on the spot, backfill timing) + Pending Image List (PLAN placeholders: which shots are waiting for which images; when the image is ready, bind REF to trigger finalization re-read) + project path + named validation items that failed (do not hide). Three anti-false-report rules: ① Do not say "images generated / video generated" (the skill delivers prompts, not images). ② Never say "the result looks great" without seeing the generated result. ③ If user-supplied material is truncated or incomplete, say so explicitly; do not pretend to have read the full text.

Intent Routing (Judged by Priority)

1. Targeted Modification: Project directory exists + instruction points to a specific shot/file/phase → only modify the corresponding parts of the relevant file; leave everything else untouched.
2. Sequel: Project directory exists + vague instruction ("continue") → check 01-06 (series: 00 + current episode) completion status. Continue from the first uncompleted phase. Series sequel → first read 00_story_state.md.
3. New Idea/New Script Full Process: A new idea or script → GATE0 questionnaire → run Phase 1a (through GATE1.5 and GATE1).
4. Live Script Revision (add/delete shots, change plot points): Project is already in progress (02 is frozen) + user wants to add shots, delete plot points, or modify a plot segment → follow the Partial Resequencing procedure below. Do not redo GATE1.5. Do not fully rewrite 03/04.
5. Phase Redo: Explicit request to redo a specific file → regenerate that file and mark downstream files according to invalidation propagation rules (consistency.md Section 6).

Live Script Revision: Partial Resequencing (Lesson Learned—03 was completely rewritten twice because of this)

Real AI video production is not a straight line: after seeing the images, users want to add shots, delete a storyline, or change a plot segment. GATE1.5 finalization locks in the story skeleton and plot point list, not the storyboard table—the storyboard table is a living document.

Partial Resequencing Four Steps (only touch affected parts):

1. Modify the Plot Point List: Add/delete/modify the corresponding lines. Mark the revision date and basis (user's original words/key points). This is the only "upstream" that needs changing.
2. Assess Impact Scope: Which scenes/characters/props do the new plot points touch? → The 02 anchoring table is only updated for new entities. Existing anchors remain untouched. Only modify if changed, then follow invalidation propagation.
3. Insert Shot Numbers Without Resequencing: Use stable shot numbers (see below) to insert new shots. All existing shot numbers remain unchanged—existing 03/04 content is not invalidated.
4. Only Write Prompts for New/Modified Shots: Append them to the corresponding sections in 03/04. Mark the revision date. Review adjacent shots with the "modify one, read three beats" rule. Do not touch anything else. When modifying prompts for an existing shot, the dialog/shot number/generation duration are frozen fields—copy the dialog verbatim from 01. After writing, perform a verbatim re-read comparison (Hard Rule 4).

Stable Shot Number Rule (Hard Gate): Once assigned, a shot number is never resequenced. Use suffix-style insertion—to add a shot between S3 and S4, write S3a (or add an "S3a (v2 new)" line in the 01 storyboard table). Do not change S4 to S5. Reason: resequencing would misalign the 03 asset reference matrix, the 04 segments, and any existing nodes on the canvas/generation platform. The real-world cost = a full rewrite of 03. Mark deprecated shots in the storyboard table as ~~S3b~~ (v3 deprecated) and keep the row number; do not delete the row.

Segment-Based Production Unit (V2.9—the actual rhythm of the user describing and producing one segment at a time): Partial resequencing is for single shots. When the user adds a complete story segment (verbally describes a new segment → needs a set of situation images → video nodes → acceptance → next segment), the production unit is a "segment" not a "shot". Follow the minimal closed loop below. Do not redo GATE1.5. Do not fully resequence the storyboard table:

1. Add Segment to List: Append new segment plot points to the 01 plot point list line by line (mark revision date + user's verbal key points). Assign segment number and stable shot numbers (suffix style).
2. Check Existing Assets: For the segment's scenes/characters/props, first check the 02 and 03 asset matrices. Reuse existing anchors and reference images directly. Only add new entries/generate new asset images for new entities.
3. Segment-Contained Production: Situation images for this segment (by L1-L4 grading) → Video segment prompts (Skeleton A) → Dialog (copied verbatim from 01). Complete the cycle and run check.py --partial. If passed, automatically continue to the next segment. After all batches (all segments) are complete, provide a unified report (quantitative results + check results + named non-passed items). For reference images that have not been generated, write PLAN-<ID> as a placeholder and continue producing normally (see Stop Discipline E2). Do not stop to wait for the image.
4. Post-Acceptance Synchronization: After acceptance → add the segment's rows to the 01 storyboard table, append the segment's section to 03/04. Update 02 only if there are new entities. Write the tail frame description into that segment's record (the SCENE CONTEXT bridge anchor for the next segment).

Relationship with the six phases: Segment-based production is not skipping phases. It slices Phases 2-6 and executes them per segment. The anchoring (02) and script skeleton (01 plot point list) remain project-wide. Within a segment, only produce that segment's images/videos/dialog/editing items. The first batch of shots still follows the rule: "first produce a complete batch of the first segment for user acceptance before scaling up."

Revision Log: After each revision round, append one change record to 01 (what was changed / impact scope (shot numbers, plot points, phases) / affected files / user's original words/key points). Do not rewrite history sections. The revision trajectory in 01 is itself the basis for recovery from interruption. Single Write Point (V2.9): Change records are only written in 01. Do not duplicate change histories in 00/02. In 02, only modify the field itself (anchor entry update). In 00, only update the story state when an episode is complete. Writing in three places = poor retrievability and guaranteed to miss an update in one place.

Generation-Side Changes Back-Write Checklist (V3.7): After modifying prompts on a canvas/generation platform, back-write three things and verify verbatim: ① the corresponding segment block in 04; ② 05 dialog (if affected); ③ 01 storyboard table (duration/bridge/revision record). Close OPEN items; update PLAN/REF bindings. Manual double-write is prone to omissions; run check.py --partial after back-writing.

Canvas/Generation-End as Source (User Modifies Directly in the Tool)

When using a Toonflow-like canvas for generation, users often modify prompts directly on the canvas, move nodes, delete nodes—at this point, the canvas is the execution truth, and 01-06 is the decision source. The relationship between them:

• Do not pursue real-time synchronization (lesson learned: relying on "sync" command to catch up is wasteful; every sync is overhead) → Instead, switch to batch-lagging synchronization: synchronize once when a generation round comes to a halt. Save the sync content as a "summary card" (node ID + one-line status + differences from the document). Do not back-fill the full text verbatim.
• Conflict Resolution: If the canvas and the document disagree and the user has already finalized on the canvas → the canvas wins. Document the differences and update the decision (do not force the canvas back to the document).
• Finalization Marker: The user-created "finalized image, save to prevent contamination" node on the canvas is an effective practice → register the finalization marker node ID in the document's asset matrix. Do not overwrite it during regeneration.
• Node ID Look-Up Only, No Guessing (V3.7): The only source for canvas node IDs is the project cross-reference table (02/03 asset matrix, canvas summary card). The agent must not infer or fabricate IDs based on memory or similarity. If the table does not have it → stop and check the table or ask the user. Do not connect to or operate on an unregistered ID (lesson learned: guessing IDs either connected to the wrong node or silently failed to execute the entire batch).
• Ref Number = Connection Creation Order (V3.15 Correction): append usually only adds new numbers (ref7/ref8), does not reorder existing ones—only need to append to the image order table in the prompt. Only if "mid-sequence insertion causes existing refs to be resequenced" should you delete all input lines and reconnect them in the final order. Regardless of the scenario, the 04 image order table must be updated synchronously, and each {{ref N}} must be verified one-to-one with its usage declaration (older canvas real-test v21/v22 inserted misaligned).
• Version Ledger for Generation-End Full Re-send (V3.9 tested; current canvas setPrompt): If the generation platform has no partial editing capability, before each full re-send, save the current prompt as a version summary (version number + changes) and write it into the 01 change record. After re-sending, compare it with the 04 document. Never rely on context memory to know the current version (in the wrong version = redo the entire segment). If the canvas software is changed, this discipline is retained. The specific operations should be rewritten for the new tool.
• Sync Trigger: User says "sync", or a generation round ends, or before entering Phase 5/6—three trigger points. Do not sync at other times.

Capability Actual-Testing First vs Locked Record (lesson learned: GATE0 locked "H3 video direct output dialog + voice reference auto-extraction" main plan, which immediately failed because the gateway-version H3 does not support audio): The capability list locked at GATE0 is a planning basis, not a guarantee. Before generation, the actual available capabilities of the tool determine reality. When the main plan fails, switch to an alternative route (voice → cosyvoice lip-sync) and record the switch reason in 01/02. Do not retry a capability already determined to be unsupported. Checkpointing (V2.9): When locking the model at GATE0, specify the vendor/gateway (different providers for the same model may have different capabilities—moma vs apiMart for H3 generateAudio: one rejects, one accepts). Before generation, test probe the current vendor for key capabilities (audio direct output / reference image count & size / duration limit). Check the model.md "Vendor Difference Memo" section for already-registered vendor differences. If the test result conflicts with the memo, the current test wins. Back-fill the result.

Single-Point Modification Review Discipline (Modify One, Read Three Beats): After modifying any shot or beat, you must re-read one beat before and one beat after it, specifically checking three things: Character position (is the position sentence/LOCATION MAP still valid?), Prop in-hand state (was it in the left hand in the previous scene? It cannot be in the right hand in this scene.), Who is present (is the default of 0 extras still true?). When writing, the spatial state is in your mind. When modifying, it is not. If you do not re-read, you will create a teleportation.

• Self-Recite Before Modifying (V2.9 tested lesson + V3.0 downgraded to self-validation): For a single-shot fine-tuning (changing camera position/shot size/composition/grip direction), before touching the prompt, first recite in one sentence your understanding of the composition (e.g., "I understand: top-down shot, she is sitting to his right, side by side, no contact between them") and write it into the 01 change record. Only ask the user if it hits the oral ambiguity list (front face/side/slight low angle, etc.) and context cannot resolve the ambiguity. Resolve ambiguities per cinematography.md's Oral Ambiguity List. The cost of reciting one sentence ≈ 0. The cost of one rework cycle = one generation + one wait. Self-recitation catches 95% of understanding deviations before pen hits paper. Only escalate to a question for genuine ambiguities.
• Situation Image Finalization Triggers Re-Read (V2.9—turns "modify one, read three beats" from a post-hoc fix into a default action): Whenever a situation image / first-frame image is finalized (including re-finalization after modification), must re-read all video segment shot blocks that reference it. Verify each block's scene description for consistency with the newly finalized image (pose/grip/position/clothing). Fix inconsistent shot blocks immediately. Do not wait for generation failure to discover it.

Similarly: Soundscape is also an action instruction—if the soundscape says "the copper bell explodes on impact", the video will indeed act out the impact. When modifying the visuals, synchronize three places (shot block scene description / AUDIO soundscape / 01 storyboard table). When modifying a cut point, read adjacent cuts (position is a continuous state).

Escalation Ladder for Unsatisfactory Results (When a shot generation fails or quality is poor, try in order):

Before entering the ladder, first check generability (prompt-rules 0.7): Does the failure indicate the shot was not generable in the first place? If so, do not rewrite the prompt; rewrite the implementation method. If the scene description itself is flawed, fix the scene.

... (truncated for translation, but the full markdown would continue and be translated similarly)