--- name: video-storyboard description: Use when designing, scripting, or storyboarding a short demo, launch, explainer, or marketing video (especially for a developer tool, app, or SaaS), OR when auditing, critiquing, or improving an existing video's narrative, hook, pacing, or storyboard. Runs a verified 6-stage process — positioning, message spine, beat sheet, script, storyboard, review — embedding StoryBrand, Before-After-Bridge / PAS / AIDA, the Pixar Story Spine, and the But/Therefore rule. Invoke whenever the work is about the STORY of a video rather than its rendering, including phrasings like "storyboard this", "what's the hook", "make the video more compelling", "the video falls flat", "script a launch video", or "audit this video". After an approved render, hand off publishing to video-assets so MP4 and AVIF release assets stay in sync. Do not use this skill for the encoding/rendering pipeline itself. --- # Video Storyboard A repeatable process for the part of a video that decides whether it works: the **narrative**. Rendering executes the story; this skill designs it. For cctop launch videos, this is the first half of the workflow: 1. Use this skill for story/script/storyboard/audit decisions. 2. Render through the repo video pipeline (`cd video && ./build.sh launch` for the launch cut). 3. After the user approves the rendered video, switch to `$video-assets` and publish with its confirmation gate. That workflow uploads `cctop-launch.mp4`, `cctop-launch-720p.mp4`, and a freshly generated `cctop-launch-preview.avif` together to the non-latest `media-assets` release. For cctop product facts, audience, feature-fit judgment, and language choices, read `PRODUCT.md` before writing positioning or scripts. Use `README.md` for current public-facing claims and supported-tool lists. It has two modes: - **DESIGN** — build a video's story from scratch (product facts → approved storyboard). - **AUDIT** — run the same lenses over a finished or draft video to find what's weak and how to fix it. Pick the mode from the request. "Storyboard a video for X" → DESIGN. "Why does this video feel flat / make it better / review this cut" → AUDIT. Everything here is built from frameworks that survived adversarial fact-checking. The frameworks are solid; many of the *numbers* floating around the industry are blog-grade rules of thumb. Where a guideline is directional rather than proven, it is marked `[directional]`. See `references/frameworks.md` for provenance, citations, and the specifics that were *refuted* (so you don't codify folklore). --- ## The core idea Most product videos fail the same way: they are a **feature montage from the product's point of view** ("here's the panel, here are the tabs, here are the themes"). They list capabilities instead of telling the story of a person whose problem gets solved. The fix is one reframe and four moves: 1. **The viewer is the hero; the product is the guide.** (StoryBrand) The story is about *them* and their struggle, not about your UI. 2. **Pick one spine** and fill it — don't free-associate beats. 3. **Connect beats by cause-and-effect** (but/therefore), never by chronology (and then). 4. **Engineer the opening for a muted, scrolling viewer** — the first frame must earn the next two seconds. --- ## Common failure modes (the floor-raisers) These are the specific ways videos break, distilled from real reviews. They generalize — check for them in DESIGN (avoid) and AUDIT (catch). Pre-empting these is most of what makes a *first* draft good instead of a third. 1. **The hook shows one thing and says another.** The opening line promises tension ("which one needs you?") while the visuals say "all fine" (e.g. every status indicator green). The first ~1.5s of *picture* must depict the problem, not just the text — a muted scroller reads the image, not the words. *Fix: put the problem-state on screen in frame one, with motion (the thing going wrong), before or under the line.* 2. **Action without payoff.** You show the click / keypress / command, but never the **result**. The viewer feels the setup and never the relief. *Fix: every action beat needs an after-beat — show the win (the session opened, the thing unblocked, the status flipping to good).* This is the Story-Spine "until finally" / BAB "After," and it's the single most common missing beat. 3. **Wrong-altitude reveal.** You open on the product's fully-bloomed internal UI and point at an interior detail, instead of how the user *first encounters* it. *Fix: start at the real moment of discovery (the menubar glance, the CLI prompt, the notification) and expand from there.* 4. **The "and then" tail.** The back third decays into a feature montage — capability slide, and then another, and then another — with the hero gone. It's where momentum should peak before the CTA, and it sags. *Fix: tie every late beat to the hero with "therefore (so you can trust it / use it with what you have)," compress, and cut vanity beats (theme galleries, spec lists) to a flash or nothing.* 5. **Product-as-hero in the belly.** The bookends are viewer-centered but the middle becomes a spec sheet — the person disappears. *Fix: keep a problem/person present even in capability beats.* ## What this skill is — and what it can't be This skill **raises the floor of the first draft and shortens each review loop** — it guarantees the lenses get applied and the known failure modes get pre-empted, every time, even by a cheaper or distracted agent. That is its value, not out-reasoning a strong model on a single careful pass (it won't; a good model already knows this craft). It deliberately does **not** encode per-video creative specifics — the exact pacing of a transition, which element pulses, what a mock screen shows. Those are taste, discovered by rendering a concrete draft and reacting to it; hard-coding them would overfit the skill and make it brittle. Capture *patterns* here; leave the *particulars* to iteration on the actual cut. --- ## DESIGN mode — the 6-stage pipeline Each stage takes one artifact and produces the next. Don't skip ahead; a weak positioning statement poisons every downstream stage. Keep each artifact short — a video is 20–40 seconds, not a feature doc. ### Stage 1 — Position · *in:* product facts + audience · *out:* one-paragraph positioning Write the story's frame **before** any script, using StoryBrand: the **viewer is the hero**, the **product is the guide** that helps them win. Name three things: - **Who** the hero is (be specific: "a dev running several AI coding agents at once", not "developers"). - **What they want** and **what's in the way** (the external problem *and* the internal feeling — frustration, loss of control, wasted time). - **The transformation**: the before-state → the after-state the product enables. If you catch yourself describing the product's features here, stop — you've made the product the hero. Rewrite from the viewer's chair. ### Stage 2 — Message spine · *in:* positioning · *out:* a chosen structure, each step filled Choose ONE spine and write a sentence for each step: - **Before-After-Bridge (default for 20–40s)** — *Before* (the painful current state) → *After* (the desirable future) → *Bridge* (the product as the thing that gets you there). Best for "storytelling in tight spaces." - **PAS** — *Problem → Agitate* (make the cost of inaction felt) *→ Solution.* Use when the pain is sharp and relatable. - **AIDA** — *Attention → Interest → Desire → Action.* Use when a hard CTA/conversion is the goal. (AIDA is a conversion spine, not a story arc — don't force it into acts.) ### Stage 3 — Beat sheet · *in:* spine · *out:* 4–7 ordered beats Generate beats with the **Pixar Story Spine** as a prompt ("…every day… until one day… because of that… until finally…"), then run the **But/Therefore test** on every seam: each beat must follow from the last with a **"but"** (tension) or **"therefore"** (consequence). If the only word that fits between two beats is **"and then"**, you have a list, not a story — cut or reorder until causation holds. This single test is the fastest way to find a flat middle. ### Stage 4 — Script · *in:* beat sheet · *out:* on-screen-text / VO script with timecodes Write the words and the timing. Hard requirements, because the median viewer is scrolling with the **sound off**: - **The first frame must work muted** and lead with **motion, not setup**. No cold logo, no slow fade-up on an empty stage. Open *in* the hero's problem. - **Answer "what is this / why do I care" by ~second 3–5.** `[directional]` Slow build is the #1 retention killer. - **End on a clear payoff and one CTA** (where to go / what to do). - Track the opening with **hook rate = 3-sec views ÷ impressions** once it ships. `[directional]` ### Stage 5 — Storyboard / shot list · *in:* script · *out:* per-beat frames Turn each beat into a frame: what's on screen, the motion, the on-screen copy, and the duration. Two rules: - **Tight body cuts (~2s), no dwelling.** `[directional]` Momentum sustains retention; static holds bleed it. - **Pick the shortest length that carries the message.** Retention scales inversely with length, so a tight 22s beats a baggy 35s. `[directional]` - **Introduce the product the way the hero first encounters it.** If they'd meet it as a menubar glance, a CLI prompt, or a notification — *start there* and expand, rather than opening on its fully-bloomed internal UI. The reveal should mirror the real moment of discovery. ### Stage 6 — Review · *in:* storyboard / animatic · *out:* approved board Before building, check the board against the **Audit checklist** below. Anything that fails goes back a stage. Treat the checklist as the definition of done. --- ## AUDIT mode — score an existing video Given a finished or draft video (a description, a storyboard, or the actual frames — Read them if available), walk the checklist and produce: a **per-lens verdict (✅ / ⚠️ / ❌ with one line of why)** and a **prioritized fix list** (highest narrative impact first). Be specific and reference the moment/timecode. Two review disciplines (both learned from this skill underperforming a sharp human reviewer): - **Don't soften.** A missing payoff (lens 7), a hook whose visuals contradict its words (lens 4), and a wrong-altitude reveal (lens 6) **break the beat — rate them ❌, not ⚠️.** A "warn" on a broken beat reads as "it's fine," and it won't get fixed. - **Name the single highest-impact fix.** After the per-lens pass, don't end on a flat list of 2–3 "top" changes — pick **the one** change that most improves the video and say so. Ranking is the value; a tie is a dodge. Run every lens — they catch different failure modes: 1. **Hero & guide (positioning).** Is the *viewer* the hero and the product the guide? Or is it a product-centric feature tour? ❌ if it mostly shows the UI doing things with no person/problem at the center. 2. **Spine.** Is there a discernible Before→After→Bridge (or PAS/AIDA) arc, or is it a montage of capabilities? Name the spine you can detect; if you can't, that's the finding. 3. **Causation (but/therefore).** Do the beats connect by cause-and-effect, or is it "feature, and then feature, and then feature"? Find the seams that are only "and then." 4. **Hook.** Does the **first frame work muted** and grab in ~2s? Is it a *felt problem* or a title card / logo / slow fade? **Do the first ~1.5s of *visuals* match the words** — if the line poses a problem, the picture must show it (don't let the text say "trouble" while the image says "all fine")? On social the first 2s decide everything. 5. **Value clarity.** Is "what is this and why care" obvious by ~sec 5? `[directional]` 6. **Discovery-true reveal.** Is the product introduced the way the hero would actually first encounter it, then expanded — or does it open on the fully-formed internal UI and point at interior details before establishing the whole? A reveal that starts at the wrong altitude is a common, easy-to-miss miss. 7. **Payoff.** Is there a clear *after* state — the moment of relief/win? A video that shows the action (the click, the keypress) but never shows the **result** has no payoff; the viewer feels the setup but not the resolution. (This is the Story-Spine "until finally" and the BAB "After.") 8. **Pacing & length.** ~2s cuts, no slow build, shortest viable length? `[directional]` 9. **CTA.** Is there a clear next step at the end? For each ❌/⚠️, give the concrete narrative fix (what to add/cut/reorder), not a production note. End by naming **the single highest-impact change** (then any runners-up), per the discipline above. --- ## Honest caveats (read before quoting numbers) - **Frameworks: solid. Numbers: directional.** StoryBrand (hero/guide), BAB, PAS, AIDA, the Pixar Story Spine, and the But/Therefore rule are well-established and primary-sourced. Every retention/timing figure (the "muted majority", "value by sec 3–5", "~2s cuts", length↔retention curve) is a vendor-blog rule of thumb — use as direction, re-check per platform, never present as proven. - **Do not codify the folklore.** Verification *refuted* the exact SB7 7-step list, the exact Story-Spine prompt wording, AIDA-as-a-four-act-story, fixed "hook formula types", and specific impression multipliers. Use the framework *principles* at the altitude above; don't invent precise step lists. - **Two known gaps:** there is no verified public playbook for how named companies (Linear, Vercel, Stripe, Apple…) structure videos, and no verified LLM storyboard-prompt framework. Don't assert specifics there. Full provenance, citations, and the refuted list: `references/frameworks.md`.