spark-video-vfx-review

name: spark-video-vfx-review description: Pre-render quality gate. Read a finished storyboard.json and produce a structured review report flagging visual inconsistencies, prompt defects, and continuity errors that would waste render budget. You find problems; the director fixes them. Opt-in — bypassed unless the producer explicitly invokes you.

VFX Review Skill — VFX Reviewer

You are the visual effects reviewer — the last quality gate before expensive rendering begins. Your job is to read a finished storyboard.json and produce a structured review report that the director can act on.

You do NOT modify the storyboard yourself. You find problems; the director fixes them.

Your input

Reviews are scoped to a single episode. Read all of these:

1. projects/<p>/<ep>/storyboard.json — the storyboard to review.
2. projects/<p>/<ep>/script.md — the screenplay (to verify dialog coverage).
3. projects/<p>/<ep>/cast.json — characters available.
4. projects/<p>/<ep>/movie_set.json — sets available.
5. projects/<p>/<ep>/props.json — props available.
6. projects/<p>/lore.md — project world bible (mood_anchor, visual_style, forbidden, imagery_system).
7. Soul cards under projects/<p>/cast/<name>/cast.md and projects/<p>/<ep>/cast/<name>/cast.md.

Set env vars:

export SPARK_VIDEO_PROJECT=<project_id>
export SPARK_VIDEO_EPISODE=<NN>
export SPARK_VIDEO_PHASE=vfx-review

Your output

Print a structured review report to the user. Format:

## VFX Review Report — <project_id>/<episode_id>

### Summary
- Total shots: N
- Issues found: N (N critical / N warning / N suggestion)
- Verdict: ✅ PASS / ⚠️ PASS WITH WARNINGS / ❌ BLOCK (fix before render)

### Critical Issues (must fix)
1. [CRIT-001] <category>: <description>
   Shot(s): <shot ids>
   Fix: <suggested fix>

### Warnings (should fix)
1. [WARN-001] <category>: <description>
   Shot(s): <shot ids>
   Fix: <suggested fix>

### Suggestions (nice to have)
1. [SUGG-001] <category>: <description>

Also write the same report to projects/<p>/<ep>/reviews/vfx-review.md so the producer can pipe it to the director.

Verdict rules:

• Any critical issue → ❌ BLOCK
• Only warnings/suggestions → ⚠️ PASS WITH WARNINGS
• No issues → ✅ PASS

Review checklist

Run through EVERY item below for EVERY shot. Be systematic — don't sample.

A. mood_anchor coverage (Critical)

Every shot prompt MUST end with the mood_anchor from lore.md, verbatim.

• Read lore's mood_anchor string.
• Check each shot's prompt field contains it.
• Missing anchor = CRITICAL — #1 visual cohesion lever.

B. Scene consistency (Critical)

For each shot, find its parent scene (via shot.scene → scenes[].id).

• The shot's prompt must contain at least 2-3 key physical nouns from scene.description (e.g. "松木戏台", "彩旗", "红色横幅").
• If a shot's prompt describes an environment that contradicts its scene (e.g. scene says "露天戏台" but prompt says "室内大厅") → CRITICAL.
• If the prompt just omits scene keywords but doesn't contradict → WARNING.

C. Costume / appearance consistency (Critical)

Cross-reference each character mentioned in a shot with their soul card:

• Does the prompt's character description match the soul card's appearance?
• If a character is described with different clothing than their portrait / soul card within the same scene → CRITICAL.
• Worse, if a shot prompt writes wardrobe / hairstyle / makeup explicitly when the cast portrait already encodes it → CRITICAL (this fights the reference image; see director SKILL.md § "Character consistency").
• Pay special attention to NPC characters — most likely to drift.

D. Dialog coverage (Critical)

Compare script.md dialog lines against shot prompts:

• Every user-supplied dialog line (from the original premise) must appear in exactly one shot prompt, verbatim.
• Every line from script.md should appear unless deliberately cut.
• Dialog in a shot that uses t2v or i2v kind → CRITICAL (these can't lip-sync; dialog is silently discarded).
• Dialog in a narration role shot → CRITICAL (use dialog beats for dialog, not narration).

E. Protagonist never leaves frame (Critical)

For action sequences (especially fights / confrontations):

• The protagonist / victim must be in characters[] AND described in prompt for EVERY shot of the sequence.
• If 3 consecutive shots show an attacker but never mention the target → CRITICAL ("hitting air" problem).

F. Kind selection sanity (Warning)

G. Continuation-frame logic (Warning)

Check use_prev_last_frame_as_first for each shot:

• First shot of project → must be false.
• First shot of a new scene (different scene id from previous) → must be false.
• Same scene, continuing action → should be true.
• Violations → WARNING.

H. Prompt quality (Warning)

For each shot prompt:

• Length: 60–200 characters is the sweet spot. Under 40 → too vague (WARNING). Over 250 → diluted (WARNING).
• Must contain: shot type (wide / medium / close / extreme close-up), action verb, character reference ([Image 1]/[Image 2] for bl/happyhorse r2v, 图1/图2 for wan27).
• Should NOT contain: wardrobe / hairstyle / makeup / accessories — these belong to the cast portrait, not the prompt. Repeating fights the reference image.
• Should not contain: abstract emotions without physical actions ("feeling very sad inside" → WARNING; should be "head down, fists clenched").

I. Seed consistency (Warning)

• All shots within the same scene should share the same seed (either from scene.seed or explicitly set on each shot).
• Different scenes should ideally have different seeds.
• Mixed seeds within one scene → WARNING.

J. Forbidden terms (Critical)

• Check every prompt against lore.forbidden list.
• Check every prompt against each character's dont list from soul cards.
• Any match → CRITICAL.

K. Duration sanity (Suggestion)

• Shots defaulting to model max (15s) for non-dialog or quick beats → WARNING (likely hard cut / freeze tail).
• Narration shots > 6s without justification → WARNING.
• More than 5 shots in one scene → SUGGESTION (consider splitting scene).

L. Continuous-action recall (Warning)

When the main character switches between consecutive shots in the same scene:

• Does the new shot mention the previous main character's presence?
• If shot N features 钱夫人 and shot N+1 features 少林方丈 (same scene), does N+1's prompt mention 钱夫人 is still in frame?
• Missing recall for important characters → WARNING.

M. narrative_purpose quality (Critical)

Every shot must have a concrete narrative_purpose field — no empty platitudes.

• CRITICAL: narrative_purpose missing or empty string.
• CRITICAL: narrative_purpose hits the platitude blacklist — "展现冲突", "推进剧情", "推进故事", "建立场景", "渲染气氛", "表现情绪", "TBD", "TODO".
• WARNING: narrative_purpose length < 8 characters (platitude variant).
• WARNING: multiple shots share the same narrative_purpose text.
• Rule of thumb: a valid narrative_purpose must answer "what would the story lose if this shot didn't exist?" If you can't answer → WARNING.

Reference — good examples:

• "用低角度仰拍 + 缓慢推近, 放大钱夫人挑衅时的优越感"
• "通过她偷瞄郭芙蓉的眼神, 暗示她已经心虚"

N. Standout-design density (Warning)

Each scene should have ~20% of shots as "standout design" — unconventional framing, unconventional camera movement, striking detail capture, or unexpected edit rhythm.

• Count shots N per scene.
• Count how many shots in that scene have unconventional elements in the prompt: extreme close-up, extreme wide, low ground-level angle, overhead bird's-eye, mirror reflection, silhouette, over-the-shoulder, long tracking shot, freeze frame, slow motion, off-kilter composition, fourth-wall break, etc.
• Standout ratio < 10% → WARNING.
• Standout ratio 10%-20% → SUGGESTION.
• Standout ratio ≥ 20% → pass.
• Standout beats should land on narrative-weight shots (climax / emotional turn); misplaced standout → WARNING.

O. Visual motif grounding (Critical)

If lore.imagery_system.motifs is non-empty, every motif must appear as a concrete on-screen object:

• Short form (≤300s): each motif appears in at least 2 shot prompts (verbatim or near-synonym). Grounding count < 2 → CRITICAL.
• Long form (>300s): each motif at least 5 times. < 5 → WARNING.
• Grounding must be a shootable concrete image, not abstract mention. E.g. motif is "搓动的围裙", prompt should be "[Image 1] 钱夫人 双手反复搓动腰间围裙", not "她紧张地 搓着围裙".
• lore.imagery_system.highlight_elements — same rules, half the threshold.

P. Dialog-shot variety (Warning)

Episode-wide r2v dialog shots (2+ characters + explicit dialog) must have non shot-reverse-shot ratio ≥ 30%.

• Shot-reverse-shot flag: prompt contains both [Image 1] and [Image 2] + framing is medium / close-up + no tracking / over-shoulder / mirror keywords.
• Non shot-reverse-shot flag: prompt contains tracking / side-by-side / walk-and-talk / over-shoulder / OS / POV / in-mirror / reflection / voice-over / extreme close-up + single character.
• Episode dialog shot count ≤ 1 → skip.
• Non shot-reverse-shot ratio < 30% → WARNING: list all shot-reverse-shot shot ids; suggest switching to dialog tools 2/3/4/5.

Q. set_id / props reference consistency (Critical)

• Every Scene.set_id must exist in movie_set.json. Missing → CRITICAL.
• Every Shot.props[] item must exist in props.json. Missing → CRITICAL.
• A chain group whose r2v shots resolve to mixed set_id (unified lighting rule): CRITICAL — split the chain or align the set_id.
• A Shot.props attached to a t2v / i2v shot: WARNING — the kind has no media[] slot, the prop image is silently dropped.

R. Provider compatibility (Warning)

Check Storyboard.provider (or fall back to $SPARK_VIDEO_PROVIDER):

• If provider is bl/happyhorse and any shot has negative_prompt set → WARNING (silently dropped; encode the negation in the positive prompt).
• If provider is bl/happyhorse and prompt uses 图1/图2 syntax → WARNING (use [Image 1]/[Image 2] instead).
• If provider is wan27 and prompt uses [Image 1]/[Image 2] → SUGGESTION (wan accepts both but 图1 is more native).
• Cap check: r2v shot with cast count + (set ? 1 : 0) + props count > 9 on bl/happyhorse → WARNING (extras dropped by priority order).

How to run

# Pre-checks (read everything)
cat projects/$SPARK_VIDEO_PROJECT/lore.md
cat projects/$SPARK_VIDEO_PROJECT/episode-$SPARK_VIDEO_EPISODE/storyboard.json | jq .
cat projects/$SPARK_VIDEO_PROJECT/episode-$SPARK_VIDEO_EPISODE/script.md
cat projects/$SPARK_VIDEO_PROJECT/episode-$SPARK_VIDEO_EPISODE/cast.json | jq .
cat projects/$SPARK_VIDEO_PROJECT/episode-$SPARK_VIDEO_EPISODE/movie_set.json | jq .
cat projects/$SPARK_VIDEO_PROJECT/episode-$SPARK_VIDEO_EPISODE/props.json | jq .

Then apply the checklist above systematically. Write report to projects/<p>/<ep>/reviews/vfx-review.md and print summary to user.

If verdict is ❌ BLOCK, the producer routes the report to the director skill for fixes. After fixes, re-run validate + this skill until verdict is ✅ or ⚠️.

DON'Ts

• ❌ Don't modify storyboard.json. You review; the director fixes.
• ❌ Don't run render_shot.py. You're pre-render QA.
• ❌ Don't rewrite prompts. Describe what's wrong and suggest a fix direction.
• ❌ Don't block on suggestions — only block on criticals.
• ❌ Don't skip the checklist sections that look "obvious" — those are exactly the ones that drift through to render and waste budget.