Film storyboard
The storyboard is where most of the owner's corrections should happen, because changing a sentence costs a minute and changing a rendered shot costs an hour. Send it before you build, and send it again (with real frames) before you record a voice.
What makes a good product-film story
Check each beat against these. Every one came from a rejected draft (see product-film/references/lessons.md).
- The viewer's pain, in their day. Name the habit or annoyance the way the viewer would say it. Test the line: after hearing it, what would a stranger think we sell? "Same numbers every day" made people think of analytics software, so it failed.
- Roles can't be misread. Show real tools by name and logo. Check every pair of adjacent lines: "Ask the AI you already pay for. It's called Nimbet." makes the product sound like the AI. Attach the name to what the product does.
- Specific, not abstract. "Your AI" as a label was unclear; Claude Desktop's real window was clear. A real Stripe dashboard beats a box labelled "Revenue".
- Range needs room. If the promise is "whatever YOU need", show 8+ kinds of people (full-screen card each), then a wall of many items mixing work, life and fun (games, pets, stickers). Fewer than ~6 "feels stuck". This needs 45–65 s; 20 s is too short.
- Real only. Every item, capability and claim works in the product today. Fill the
claimfield with where it's proven (a file, a doc, a test). If the story needs something the product can't do, raise it with the owner: build it or cut it. - Understand each shot before you write about it. Write the
whyfor every beat. If you can't say what a shot is for, ask the owner. (A pet line was written over a shot that actually showed people's own custom widgets.) - Every line readable. On-screen text: ~0.3 s per word + 1 s, never under 1.5 s fully visible.
- End on the action, with the name and the URL, and the nominative-use line if any brand appeared.
Steps
- Read the approved brief,
reference/NOTES.md, the live product and site, and the lessons file. - Draft beats in
storyboard.json(format in the script's header):Before the film exists,{ "title": "…", "subtitle": "draft 1 · 16:9 · 60 s", "directions": ["A · …", "B · …"], "beats": [{ "t": "0.0–4.0", "still": "review/sketches/01.png", "picture": "…", "onscreen": "…", "vo": {"A · …": "…", "B · …": "…"}, "sfx": "…", "why": "…", "claim": "…" }] }stillcan be a quick sketch or a frame from the reference with a note; after, always a REAL rendered frame (node scripts/render.mjs --at …). - Directions. When the angle is open, write 2–4 directions that differ in idea, not wording (e.g. "Tips the viewer can use", "The daily annoyance", "What your AI already knows about you"). For each: one-line idea, the risk, and who it suits. Put your pick first.
- Build the page:
It opens with each direction's voiceover as one paragraph (the eyes-closed read), then every beat with its frame.python3 ~/.claude/skills/film-storyboard/scripts/storyboard.py storyboard.json review/storyboard.html - Self-check before sending: read only the transcript paragraph. Does it make sense with eyes closed? Any line that could be misread? Any "your X, your Y" list, triad, or repeated word? Any claim with no proof?
- Review gate. Send the page (SendUserFile, display render) and ask: which direction, and which beats to change.
Add the stage-2 questions from
product-film/references/question-bank.md(opening, how roles are shown, persona format, characters, UI realism). Wait for a clear yes. Commitstoryboard.json.
After approval
Keep storyboard.json as the source of truth: shot timing in the film and phrase placement in the voiceover both come
from it. When the owner changes a beat later, change it here first and regenerate the page.