higgsfield-shotlist-director

# Higgsfield Shotlist Director

Turn a brief into **one connected shotlist** — not a pile of separate prompts.
The deliverable is a single editable HTML artifact the user opens in a browser,
ticks scenes off as they shoot, and comes back to you to revise. This is the
artifact-shaped workflow a fully-AI commercial actually runs on: lock a global
look once, declare the cast/props/locations once, then emit named per-scene
prompts that all inherit both.

> **This skill is the connected layer on top of `higgsfield-seedance`.** It does
> not reinvent the prompt grammar — every per-scene prompt obeys the six-slot
> formula and the Prompt-Craft Laws in `../higgsfield-seedance/SKILL.md`, and
> every prompt is preflight-linted before delivery. What this skill adds is the
> *document*: the global Style Prefix, the `@`-glossary, the per-scene numbering,
> and the edit-once / per-scene-override semantics that keep 25 prompts in sync.

## QUICK FACTS
- Output = **one self-contained HTML file** (inline CSS/JS, no deps), not loose prompts [→](#what-you-produce)
- Three structural layers, top to bottom: **Global Style Prefix → `@`-asset glossary → named per-scene prompts** [→](#the-three-layers)
- Per-scene prompt law: `Style → Characters → Scene → CUT 1..N`; each prompt targets **15s**; split long scenes as `3a/3b/3c` [→](#per-scene-prompt-law)
- [OFFICIAL] Density heuristic: group rows when ALL of {same cast, same location, one emotional unit, ≤15s, inside length limits}; split on ANY of {location cut, cast change, setup change, performance arc, insert} — **don't fragment grief**; complexity budget + auto-enrichment defaults for thin briefs [→](#prompt-density-grouping-shot-rows-into-15s-envelopes)
- Whole-sequence checks before delivery: **tempo budget** (cut durations sum exactly to runtime; one 6–8s hero hold) + **monotony audit** (no 3 consecutive cuts sharing shot size AND camera move) [→](#sequence-tempo-and-variety)
- Continuity carries exits too: an **Off-screen line** (exit side + last state) per just-departed character keeps re-entry direction legal [→](#per-scene-prompt-law)
- **Edit-once-propagates**: change the prefix once → it changes in every prompt; per-scene **override** lets one scene break the global look [→](#edit-once-and-per-scene-override)
- Differentiators over a bare shotlist generator: **preflight linter**, **reference-role lanes**, **Elements `@`-auto-attach**, **failure-mode awareness**, **acceptance-rate logging** [→](#what-makes-this-outclass-a-bare-generator)
- English prompt text only (Seedance expects English), even if the user writes in another language [→](#workflow)

---

## What you produce

A single `shotlist.html` (saved to the user's outputs and presented). It is
**self-contained** — inline CSS, inline JS, zero external dependencies — so the
user can open it offline and it just works. Structure:

1. **Title bar** — project name (infer from the brief; "Untitled" if unclear).
2. **Global Style Prefix** — collapsible block at top, applied to every prompt.
3. **`@`-asset glossary** — the cast/props/locations declared once.
4. **Scene list** — numbered scenes, each with a checkbox (progress saved in
   `localStorage`), a one-line scene description, and one or more copy-ready
   prompt blocks (`Prompt 3a · 15s`, `Prompt 3b · 15s`).
5. A short "how to use" note (checkboxes auto-save; ask Claude to revise).

The Style Prefix appears **once** in the collapsible block **and** is prepended
verbatim to every prompt's copy-block — so the user copies one prompt into
Seedance and it works standalone, no reassembly.

---

## The three layers

### 1. Global Style Prefix

A single style block glued to every prompt in the document — edit it once and it
changes everywhere. It locks the film's global look: format/resolution, lighting
doctrine, colour ratio, lens/shutter, skin realism, acting register, physics,
composition, continuity, frame rate, and audio convention.

Ship the reusable fill-in-the-blanks block from
[`../../templates/seedance/global-style-prefix.md`](../../templates/seedance/global-style-prefix.md).
**Always check the conversation first** — if the user pasted a custom prefix, use
that one verbatim. Otherwise use the template default.

### 2. `@`-asset glossary

Declare every recurring asset once, with a stable `@`-name, then register each
under **Elements** in Higgsfield with the **same name** so pasting a prompt
auto-attaches the right images:

```
@hero — main character          @boss — side character
@headphones — product           @sneakers · @bag · @skydancer — props
@kitchen · @stadium · @street — locations
@s_hero — athletic-look hero     @s_hero_wet — sweaty post-run hero
@music_track (audio_1.wav) — motion locks to this beat
@street_schematic (image_1.png) — top-down position map
```

The slot→role discipline (`@Image1` = character, `@Image2` = costume, `@Audio1`
= rhythm…) comes from `../higgsfield-seedance/SKILL.md` § Reference Roles →
Per-Image Role Convention. **Multi-state variants get their own locked entry**
(`@s_hero_wet`), built on purpose up front — asking the model to "sweat him up"
later makes it improvise and the face drifts.

**Each glossary entry also carries a fidelity grade** — a role says what job the
asset does, the grade says how much of it must survive into the pixels:
*full-preserve* / *partial-preserve (name the parts)* / *attribute-transfer (name
the target it lifts onto)* / *loose-guide*. One word per line is enough
(`@headphones — product, full-preserve`); the grades and their prompt phrasing
live in `../higgsfield-seedance-2-5/SKILL.md` § Reference Roles → Fidelity.
Without a grade, "use @image4 for the coat" silently means whatever the model
felt like keeping that day.

### 3. Named per-scene prompts

Every scene is numbered (`1`, `2`, `3`…) and split into named 15-second prompts
(`1a`, `1b`, `2a`). One checkbox per **scene**, even when split across `3a/3b/3c`.

---

## Per-scene prompt law

Every prompt follows this exact order,