| name | audit-motion |
| description | Analyze supplied videos and deterministic website recordings, pair visual timelines with DOM, scroll, media, canvas, WebGL, and network telemetry, and produce evidence-labeled motion manifests and QA checkpoints. Use for website-clone motion audits involving scroll triggers, sticky or parallax scenes, scrubbed video, canvas/WebGL animation, responsive motion, or reduced-motion behavior. |
Audit Motion
Turn a recording plus synchronized runtime telemetry into a reviewable motion
contract. Preserve the boundary between visible behavior and implementation
mechanism.
Inputs and gate
Require:
- a clone contract, target URL, scenario name, viewport, and capture time;
- an untouched source video or deterministic browser recording;
- telemetry artifacts when the audit makes DOM or implementation claims.
Stop and record an unknown when the recording, capture conditions, or telemetry
cannot support a material conclusion. Do not dispatch a builder until the motion
manifest and human motion audit are frozen.
Workflow
-
Inventory and hash. Verify ffmpeg and ffprobe, then probe every source:
node .claude/skills/audit-motion/scripts/probe-video.mjs \
path/to/recording.mp4 --output path/to/probe.json
-
Build the visual timeline. Create an evenly sampled contact sheet and its
time-indexed JSON sidecar:
node .claude/skills/audit-motion/scripts/contact-sheet.mjs \
path/to/recording.mp4 --output path/to/contact-sheet.png \
--metadata path/to/contact-sheet.timeline.json --count 12
For a narrow ambiguous range, optionally use video-use timeline_view as a
visual-timeline adapter:
node .claude/skills/audit-motion/scripts/video-use-timeline.mjs \
path/to/recording.mp4 4.2 7.8 --output path/to/range.png \
--timeline-view /absolute/path/to/video-use/helpers/timeline_view.py
video-use is not a webpage instrumentation engine. It cannot supply DOM,
scroll, canvas, WebGL, media-element, or network evidence. Do not install it
merely for this audit; the bundled contact sheet is the dependency-light
fallback. Transcribe only when speech timing materially affects the motion
finding. Skip transcription for silent UI, scroll, parallax, canvas, and
WebGL audits.
-
Align telemetry. Normalize video time, capture monotonic time, wall-clock
time, scroll pixels/progress, and media time. Pair visible checkpoints with
telemetry samples; never infer synchronization from filename order.
-
Classify events. Separate discrete transitions from continuous mappings.
Record trigger, state A/B, time or scroll bounds, duration, easing, stagger,
responsive behavior, reduced-motion behavior, and unknowns. Read
motion-taxonomy.md for the classification
rules.
-
Apply evidence labels. Use exactly measured, observed, inferred, or
invented. A rendered frame proves appearance, not the animation library or
source mechanism. Read
evidence-boundaries.md before making
mechanism claims.
-
Write the artifacts. Produce motion-manifest.json against
docs/research/schemas/motion-manifest.schema.json and a time-coded
MOTION_AUDIT.md. Keep source behavior separate from the implementation
reading.
-
Validate.
node .claude/skills/audit-motion/scripts/validate-motion-manifest.mjs \
docs/research/<target>/motion-manifest.json \
--schema docs/research/schemas/motion-manifest.schema.json \
--root . --check-artifacts
-
Freeze QA checkpoints. Include static states, critical discrete event
timing, normalized scroll progress, viewport variants, and reduced-motion
outcomes. Replay the same deterministic scenarios against the clone.
Capture guidance
Read capture-telemetry.md before designing or
reviewing browser instrumentation. Read
video-use-integration.md only when using
the optional adapter.
Preserve source files unchanged. Write probes, sheets, timelines, telemetry,
manifests, and audit notes to separate artifact paths.
