@impractical-ai/motion 0.1.5 → 0.1.7

package/assets/impractical/SKILL.md

@@ -51,6 +51,19 @@ Gather from the user (ask only for what's missing):
 - **Value prop** (required): one or two sentences on what ships and why it matters.
 - Optional: their product's front-end code, a brand URL, screen recordings.
 
+Before `create_video`, write a compact creative contract. This is a planning
+record, not a new scene format:
+
+- audience
+- the single idea the viewer should remember
+- the visual moment that proves it without explanatory copy
+- how the reference's hierarchy/pacing will be translated rather than copied
+- the real product source (and whether anything must be reconstructed)
+- opening, proof, and payoff
+
+When the local quality-loop experiment is enabled, pass that contract as
+`creativeContract` to `create_video`. The tool will reject an unplanned start.
+
 If they gave a brand URL and no kit exists yet:
 
     brand_list
@@ -93,8 +106,8 @@ Craft, briefly — the full language is `guidance.motionDirection` in the
 `motion_context` result. That copy is live and versioned; this summary is a
 snapshot, so when the two disagree, the tool result wins.
 
-- **Beat it out before writing code.** Every beat needs a time, a thing on
-  screen, and a move. A beat with no move is not a beat.
+- **Beat it out before writing code.** Every beat needs a time, a visible
+  subject, and a narrative purpose. An intentional reading hold is valid.
 - **Text enters on `rise`** — `text.reveal(el, 'rise')` on `promo-out`, lines
   ~0.2s apart. Do *not* default type to `'blur'`: word-by-word de-blur reads as
   out-of-focus, and across a stagger it turns to mush. Blur is for whole-frame
@@ -105,9 +118,10 @@ snapshot, so when the two disagree, the tool result wins.
   dives only. Never leave an ease unspecified; never put `ease-in-*` on an
   entrance. The promo subset: `promo-out`, `promo-soft`, `promo-inout`,
   `promo-in`, `launch-out`.
-- **Fast**: entrances 0.4–0.6s, exits shorter, staggers ~0.2s apart, nothing
-  over 1s but a deliberate hold drift or slow push.
-- **Nothing is ever static.** Every hold carries a slow drift or camera push.
+- **Decisive**: entrances 0.4–0.6s, exits shorter, staggers ~0.2s apart.
+  Longer movement needs a narrative reason; important states may hold still.
+- Budget one primary and at most one supporting motion. Keep backgrounds stable
+  unless their movement is explicitly authored.
 - Hold long enough to read. A beat that looks legible scrubbing the timeline is
   usually still too fast on screen.
 - Cut hard between sections; crossfading backgrounds reads as cheap.
@@ -169,9 +183,42 @@ nearly free.
 shows text clipped, an element off-frame, or a blank region, fix it and look
 again. This is the difference between shipping a video and shipping a guess.
 
+When the `get_motion` tool is available (the local motion lab experiment),
+prefer it as the first look after every preview build:
+
+    get_motion  { draftId: "..." }                       // whole scene
+    get_motion  { draftId: "...", from: 4.8, to: 6.4 }   // one weak window
+
+Static frames measure composition; `get_motion` measures motion — dense
+contact sheets where the difference between adjacent tiles IS the motion,
+plus measured pixel change per interval, dead-air spans, and the timeline's
+actual tweens with any that run without producing visible change. Fix what it
+flags, then use `get_frames` for composition close-ups.
+
+With the quality loop also enabled, the final review is two-part and export
+requires both on the same revision: `get_frames { reviewMode: "final" }` for
+composition and legibility at native resolution, and
+`get_motion { draftId, reviewMode: "final" }` for full-duration motion
+coverage at one frame in five.
+
+For a new launch video, build and review the proof beat before completing the
+rest. When the local quality loop is enabled:
+
+    get_frames  { draftId: "...", times: [/* proof beat */], reviewMode: "proof" }
+
+For the final pass, review at least eight representative timestamps including
+`t=0` and the settled closing frame:
+
+    get_frames  { draftId: "...", times: [/* whole timeline */], reviewMode: "final" }
+
+The final critic scores the visible result—not the code or effort—on narrative
+clarity, visual proof, product authenticity, composition, legibility, pacing,
+reference fidelity, and technical integrity. Use timestamped evidence. A weak
+score is a revision brief, not permission to describe the cut as “clean.”
+
 ## 5. Export and hand off
 
-    export_video  { draftId: "..." }
+    export_video  { draftId: "...", qualityReview?: {/* required by local quality loop */} }
     job_status    { jobIds: ["<returned job id>"], wait: true }
     studio_link   { projectId: "...", slug: "..." }