@slatesvideo/shared 0.5.3 → 0.5.5

package/skills/slates-vision-feedback-loop.md

@@ -27,18 +27,65 @@ The code is the FORMAL reference. The label is human texture. Use both: `IMG-A12
 
 `slates_generate_video`, `slates_generate_motion_transfer`, and `slates_generate_lip_sync` now show you their reference assets **inline** on the confirm response. You don't need to fetch them yourself — but you DO need to look at what comes back, revise the prompt if the references suggest a different motion/framing, and only then re-call with `confirm=true`.
 
+## 🔴 The still-gate — never animate a bad frame
+
+<!-- @inject:still-gate -->
+**A visible defect in the still is already a STOP.** Do not animate it. Fix the frame first, then move to motion — and go to motion only when the crop passes the still scan and you genuinely need movement to confirm an uncertain edge, reflection, or object.
+
+This is a **cost** rule as much as a craft rule: a 1080p/10s premium video generation costs many multiples of an image re-roll, and video is where a defect stops being fixable. Anything wrong in the still gets worse in motion — soft geometry mushes, broken-but-plausible objects fall apart, oily textures start crawling. **Animating a known-bad frame is the single most expensive mistake in the pipeline.** Re-rolling the image is the cheap move; re-rolling the video is not.
+<!-- @end:still-gate -->
+
 ## The pattern
 
 1. **Generate.** Call `slates_generate_image` with a prompt. The result is in your context as an image content block.
-2. **Evaluate against the brief.** What did the user actually want? Are the elements right? Composition? Lighting? Subject identity?
+2. **Evaluate on TWO axes — they are different questions:**
+   - **Brief-conformance** — what did the user actually want? Are the elements right? Composition? Lighting? Subject identity?
+   - **Defects** — run the slop rubric below. *A frame can match the brief perfectly and still be slop that mushes the moment it moves.* Checking only the first axis is how a bad frame reaches an expensive video call.
 3. **One of three outcomes:**
    - **Right** → save it (bind to a frame, character slot, etc.) and move on.
-   - **Close, but adjustable** → refine the prompt with a specific delta ("wider shot", "warmer light", "remove the second figure"), regenerate **once**.
+   - **Close, but adjustable** → refine with a specific delta, regenerate **once**.
    - **Wrong direction** → ask the user before regenerating. Don't burn credits on prompt-thrashing.
 
+## The defect rubric — four slop tells
+
+| Tell | What it looks like | Why it matters downstream |
+|---|---|---|
+| **Light with no transitions** | Flat-black pits instead of a shadow ramp; light that stops rather than falls off | Transfers onto every character or object added into that plate later |
+| **Broken-but-plausible objects** | Crates, railings, hardware, mechanisms you can *almost* read but that don't resolve | Turn to mush in motion, and the model multiplies them |
+| **Local logic breaks** | An effect present in only part of the frame — rain scratching one corner, wet ground under one figure | The video model's physical logic breaks along with it |
+| **Oily textures** | Soapy, licked-smooth surfaces that have lost their material identity | Reflections crawl in motion; the plate can't hold continuity |
+
+### Per-model accents — check the one you actually used
+
+- **Nano Banana Pro** (`nano-banana-pro`) — ruler-straight symmetry, everything parallel and square, flat even light, pretty but staged/stock, textures reading as 3D render rather than photograph. **It hyperbolizes every edit**: ask for graffiti on one wall and the whole location gets tagged.
+- **GPT Image 2** (`gpt-image-2`) — microcontrast to the ceiling, hard halos on every edge, no depth or bokeh, white balance pulled warm until the frame yellows, plastic licked-smooth materials. Worst tell: **one sickly texture pattern laid over the entire frame**.
+
+> ⚠️ These are accents for **`nano-banana-pro`** and **`gpt-image-2`** specifically. `nano-banana-2` is a **different model** (Gemini 3.1 Flash Image vs NB Pro's Gemini 3 Pro Image) and we have **no evidence** about its accent. Do not inherit one — say nothing rather than warn about a failure mode you can't substantiate.
+
+## Where the fault lives — triage before you change anything
+
+We say "one specific delta per regeneration" but that only helps once you know *which* variable to move. Diagnose first:
+
+| Visible pattern | Diagnosis | Fix |
+|---|---|---|
+| The defect exists in the source asset, or stays tied to the same feature when the direction changes | **Source asset** | Fix the sheet / plate, not the prompt |
+| Source is clean, and the defect changes when only the suspect motion clause changes | **Motion direction** | Fix the prompt |
+| Controls conflict, or the failure follows neither variable | **Inconclusive** | Narrow the test — change less, not more |
+
+**Review routes; it is not pass/fail.** Geography melts → fix the location. Identity drifts → fix the character sheet. Assets are sound but the action is wrong → fix the video direction. Wrong idea entirely → reopen the brief with the user.
+
+**Correct the earliest broken handoff.** Polishing a downstream symptom hides the source and guarantees it resurfaces in the next shot built from the same asset.
+
+## Baseline hygiene — isolate the variable you're testing
+
+When the **character** is the question, keep the location out of it: test on a plate that already holds its own geometry, depth, materials, and light. **A broken plate gives every character failure a second plausible cause**, and you will spend re-rolls deciding which one you're looking at. The same applies in reverse — test a plate empty before you populate it.
+
 ## Refinement rules
 
 - **One specific delta per regeneration.** Don't change five things at once — you won't know what helped.
+- **Rewrite the FULL prompt on every iteration — never a diff, never a fragment.** Change one decision, then re-emit the whole prompt so every slot still agrees with every other slot. This composes with the rule above rather than replacing it: *one delta* governs **what changes**, *full rewrite* governs **how you re-emit it**. A patched fragment leaves the old slots stale and silently contradicting the new one.
+  - On **Seedance**, a re-emit must keep the `Shot N` structure intact — see `slates-prompting-seedance`.
+  - **Exception — Omni Flash Edit.** Long prompts documentedly destroy its fidelity. There the rule inverts: one short instruction plus *"Keep everything else the same."*
 - **Anchor with references.** If the result drifted from the user's intent, attach the *previous best* generation as a reference image alongside the original brief.
 - **Use `slates_get_asset_image`** to pull a previously-generated image back into context if you need to compare against a fresh generation.
 - **Use `slates_edit_image`** for surgical tweaks instead of full regeneration when ~90% of the image is right — `sourceAssetId` = the asset, `prompt` = the change only. Edits preserve composition and identity; full regen rolls the dice. Recipe: `slates-edit-and-iterate`.

package/skills/slates-character-turnaround.md

@@ -1,55 +0,0 @@
----
-name: slates-character-turnaround
-description: Build a Slates character from a reference image — generate the turnaround sheet and expression sheet, bind both to the character's slots so the user sees the character card update live. Use when the user wants to "create a character", "build a character from this image", "generate a turnaround for X", or starts any storyboard-flow that needs consistent character references.
----
-
-# Character turnaround — Slates workflow
-
-Slates stores characters with two image slots: turnaround (full-body multi-angle) and expression sheet (face close-ups). At scene time Slates attaches BOTH via `@character` mentions — the turnaround for body/proportion/outfit, the expression-sheet close-ups for high-res facial detail. Building them well = consistent character across every frame.
-
-## Workflow
-
-### 1. Get the reference
-The user has either:
-- Pasted/uploaded an image of the character (real person, drawing, AI render).
-- Described the character in text only.
-
-If image: upload it as a reference (`slates_upload_reference_image`).
-If text only: skip step 2's reference and generate the turnaround from prompt-only (less consistent — warn the user).
-
-### 2. Create the character record
-`slates_create_character` with:
-- `name` (ask if not given)
-- `description` — 1-2 sentences, *visual* only ("tall, dark hair, scar over left eye"), not personality.
-- `style` — leave as the source's own medium by default. Only name a transform if the user wants one (e.g. anime → realistic).
-
-### 3. Generate the turnaround sheet — the identity anchor
-- Use `slates_generate_image` with a prompt like:
-  > "Character model reference sheet with 4 full body views of the same character: front view, back view, left side profile, right side profile. Neutral pose, neutral expression, consistent appearance across all views. Preserve the artistic medium and visual style of the reference (photo / anime / illustration / 3D / painterly). Render on a plain neutral-grey background with flat, even, shadowless lighting so the sheet captures identity, not scene lighting. No text, no labels, no captions. {character description}"
-- **Flat light + plain background is the whole point.** A studio-lit or scene-lit sheet bleeds its lighting into every later generation (the "green-screen-pasted-in-front-of-mountains" failure). Reference prep beats prompting here.
-- To transform the medium (e.g. "make her a real person"), append a plain-language instruction; otherwise the source style is preserved.
-- Pass the reference image as a reference. Resolution: **2k** (4k wastes credits at sheet scale — no identity gain).
-- Estimate cost first.
-- When the result returns inline: evaluate against the reference. Same character? Right angle count? If off, refine the prompt with the explicit angle list and regenerate once.
-- When right: bind via `slates_set_character_turnaround_asset` (the user sees the card update).
-
-### 4. Generate the expression sheet — the close-up face reference
-- Prompt:
-  > "Character expression reference sheet with 3 head-and-shoulder portraits side by side: neutral on left, genuine smile showing teeth in center, serious frown on right. Same character, same flat even shadowless lighting and plain neutral-grey background as the turnaround. {character description}"
-- Pass BOTH the original reference AND the just-generated turnaround as references for max consistency.
-- Same model, **2k**.
-- On success bind via `slates_set_character_expression_asset`.
-
-### 5. Hand back
-> "Character {name} ready. Turnaround + expressions bound. Use `@{name}` in any prompt — Slates attaches both sheets and names them as one person so the face stays consistent."
-
-## Why both sheets (don't gate them)
-At scene time Slates attaches the turnaround AND the expression sheet and cites BOTH inline under the same name — `{name} (images N and M)`. That shared NAME — not a withheld expression sheet, and not an injected "use for identity / render neutral" essay — is what tells the model they're ONE person and stops the multiple expressions from averaging the face to a midpoint. (Naming-as-one-entity is each model's own official lever: NB2 "assign a distinct name", Seedance "Reference Subject_N in Image_N".) The close-ups carry far more facial signal (eyes, teeth, skin) than the postage-stamp faces in a full-body turnaround, so attaching both is a fidelity win. Critically, the app injects NO wardrobe/expression/lighting directive — the user's scene prompt owns all of that, so `@{name}` in a movie-still injection keeps the still's own clothing and lighting. The trend is MORE references (video/audio/3D into newer models), all addressed by name — lean into attaching rich refs and let the naming do the work.
-
-## Anti-patterns
-
-- **Don't** studio-light or white-background the sheets. Flat, even, shadowless light on a plain neutral-grey background — or the lighting bleeds into every scene.
-- **Don't** generate turnaround and expressions in one prompt. Slates expects them as two separate assets in two separate slots.
-- **Don't** skip binding. The slots are what the storyboard pipeline reads — an unbound asset doesn't help downstream.
-- **Don't** invent character details. Stick to what's in the reference image and the user's description.
-- **Don't** use 4k unless asked — wastes credits, no quality gain at sheet scale.