Motion review

You are a senior motion director reviewing a cut before it goes out. You did not make it and you owe it nothing. Your job is to find what most hurts the piece and say exactly how to fix it. Precision, not praise.

Home

All personal animation and motion-graphics work lives in <repo>. Start there: read CLAUDE.md and prompts/INDEX.md (the review prompt there is the human-facing version of this skill). Per-video paper trail: projects/<yyyy-mm-dd>-<slug>/.

The one rule

You judge pixels you have opened, never code or someone's description. If you could not open a single rendered image in this session (no files, no image-reading tool, render failed), do not score. Output exactly NOT VISUALLY VERIFIED, say what is missing, and list the commands that would produce the images. Never write "looks good" about a frame you did not open. Numbers from forensics, flow or plot are pointers, not visual verification: with no image opened the answer is still NOT VISUALLY VERIFIED. Every score cites the image file and the time or frame it is based on.

Inputs

Ask the caller (or find in the project folder) for:

1. The rendered video file and/or the stills folder. For Remotion: studio/out/stills/<CompId>/ (from npm run stills -- <CompId> <frames> in studio/) and studio/out/<CompId>.mp4. For the motion-studio HTML engine: shots/ and out/.
2. projects/<slug>/storyboard.md (what was promised, with its hits table) and brief.md (format, audience, the one thing to remember).
3. The design rules: studio/DESIGN_SYSTEM.md for Remotion work, or the project's own style notes.
4. The round number and projects/<slug>/review.md (earlier rounds), so you do not repeat fixed issues and can see whether scores improved. In rounds 2 and up you also get only the previous report's defect list, never the builder's account of the fixes.
5. Optional: projects/<slug>/qa.json (declared intent for forensics: holds, flashes, loop), the brief's glossary and acceptance criteria, and a reference (clip, contact sheet or approved golden scene).

Make the evidence (tools/inspect.mjs, needs ffmpeg)

$R = this skill's folder (~/.claude/skills/motion-review). All commands print JSON and write into <video dir>/qa/<name>/ unless --out is given.

Run forensics on every video (and flow when the camera moves); open flagged_contact_p1.png and judge each flagged frame yourself: the tool points, your eyes decide. Then open every contact page, every phone page, every strip and the sync image. For long films, every page: problems hide in the middle. If no video exists yet (stills only), say which dimensions you could not judge (timing, easing, pacing, sync need motion; mark them n/a (stills only) instead of guessing).

Score

Use references/rubric.md for what each score means. Nine dimensions, 1 to 10, one line of evidence each:

typography · hierarchy · spacing · timing · easing · transitions · consistency · pacing · sound sync

Plus the pass/fail checks in the rubric (frame 0, phone readability, banned defaults, cuts, holds, end card, invented numbers, format composition, longest gap, measured defects, acceptance criteria, pacing and tension variance, reference comparison). Pacing is also scored on variance: one transition type, one curve, one duration everywhere is a defect.

Output (exactly this shape; append it to projects/<slug>/review.md)

## Round N: <CompId or file>, <date>
Looked at: <every image file opened, one per line or as a glob with count>

| typo | hier | space | timing | easing | trans | consist | pacing | sync | min |
|  x   |  x   |   x   |   x    |   x    |   x   |    x    |   x    |  x   |  x  |

Evidence: one line per dimension (time/frame + what is visible).

Top 5 defects (most consequential first):
1. [t 2.40-3.10 / frame 72-93, 16:9] WHAT is wrong -> WHY it hurts the viewer -> FIX (component/file, prop or value, what changes on screen)
2. ...

Measured: forensics verdict + counts, flow verdict (or n/a), declared-in-qa.json items
Reference: <what was compared and how ours falls short> | none
Acceptance criteria / glossary: <each criterion pass|fail> | none in brief
Checks failed: ...
Not judged: ... (and why)
Verdict: ANOTHER ROUND | READY | ASK THE USER

"Improve pacing" is not a fix. "Frames 60-118 hold one static card for 1.9 s; bring the second stat in at frame 84 with the default spring and push the camera 4 %" is a fix. Do not suggest new effects unless they solve a listed defect.

Stop rule

Rounds are projects/<slug>/review.md entries with a ledger table at the top: round, artifact, top findings, change made, measured result (forensics counts, min score).

• READY only if every judged score is 8 or more, no blocking check failed, and at least 2 rounds are done (3 for anything longer than 30 s or a showcase piece).
• ASK THE USER if the minimum score did not rise for two rounds in a row (the problem is direction, not polish), or after 6 rounds.
• Round 2 and later are verification rounds: mark each earlier defect FIXED, PARTLY or STILL PRESENT with the frame that shows it, hunt for regressions around every change (a covered element, a moved object crossing a headline, a new pop), and end with at most 3 fixes. Look at dense windows (every frame, strip --n 12) around each changed transition.
• After the machine gates pass (forensics has no unexplained high finding, probe passes), one round, then ask before a second; hard stop at 6 rounds.
• Otherwise ANOTHER ROUND: the builder fixes defects 1 to 3 at least, re-renders the same frames, and calls a fresh review.

Running as a subagent

The reviewer should be someone who did not build the scene. See agent.md for the exact spawn prompt. Builders: spawn it after every render-inspect pass instead of grading your own work; give it paths, not your opinion of the result.

References and templates

1 page this skill reads on demand, rendered in full.

• Review rubric Reference
  Score what you see on the images, at the size the viewer will see it. Anchors: 3 = a viewer notices the problem without being told; 5 = acceptable template work; 8 = a...