/build-product-demo

name: build-product-demo
description: Plan, produce, or diagnose evidence-backed product demo videos and screen-recorded promotional walkthroughs. Use when the user asks to make a product demo, launch video, feature showcase, app walkthrough, demo reel, or polished recording; wants every important capability shown without a slow feature tour; asks to remove dead time or fix narration-to-action pacing; or needs a repeatable script, capture plan, and verified final media. Do not use for fictional commercials with no real product proof, general-purpose video editing, or documentation-only tutorials that do not need a promotional narrative.

Build Product Demo

Turn verified product behavior into a compact proof story. Treat the final media as an executable claim about the product, not as a decorated feature list.

Choose the mode

• **Plan**: inspect the product and produce the brief, evidence inventory,

feature coverage, director treatment, script, and beat plan.

• **Produce**: complete the plan, create deterministic setup and capture

tooling, record, edit, and verify the final media.

• **Diagnose**: inspect an existing demo, identify the first broken layer, and

revise the smallest responsible artifact. Check truth, story, visible state change, attention, narration/action alignment, capture, then encoding.

If the user asks to “make” or “finish” the demo, default to Produce. Do not stop at a script while safe, in-scope production work remains.

Establish the boundary

1. Resolve the exact product repository, revision, runtime, audience, channel, target duration, aspect ratio, language, available assets, and publishing scope. Inspect before guessing. 2. Read repository instructions and existing demos, screenshots, tests, fixtures, launch scripts, and marketing claims. Search before adding a new recorder or seed path. 3. Separate immutable product facts, creative choices, and missing production facts. Do not turn an unknown into a visual claim. 4. Select one reference benchmark: the user's strongest previous demo, a product-native launch video, or a clearly named quality bar. Record what to preserve and what to avoid. Do not rely on generic taste words. 5. Choose one audience doubt and one proof proposition. Complete:

`The audience doubts whether [product claim]. The demo proves [outcome] by showing [observable change].`

6. Define the opening and landing state. Reject a concept whose product or audience state is materially unchanged at the end.

Read [directing.md](references/directing.md) before selecting features or writing beats. Read [production.md](references/production.md) before recording, generating narration, or using deterministic fixtures.

Build the evidence inventory

Classify every candidate claim:

| Level | Evidence | Demo use | |---|---|---| | E1 | Fresh live execution with retained output | May be shown as working | | E2 | Current code plus focused passing test or fixture replay | May support a bounded claim; disclose fixture use | | E3 | Current documentation or marketing copy only | Treat as a lead; verify before showing as working | | E4 | Plan, issue, mockup, or unfinished path | Exclude or label explicitly as planned |

Create `feature-coverage.md` and rank each capability as:

• **core proof**: complete cause → action → result;
• **differentiator**: memorable evidence supporting the proposition;
• **supporting evidence**: fast proof that reduces doubt;
• **exception entry**: show a truthful state or recovery entry without

deliberately damaging the product;

• **excluded**: unfinished, redundant, unverifiable, visually unreadable, or

outside the audience decision.

Do not modify product behavior merely to make the demo pass unless the user also asked for that product change.

Direct the proof story

Write a compact treatment with:

Audience doubt:
Proof proposition:
Opening state:
Turning proof:
Landing state:
Point of view:
Information strategy:
Visual progression:
Sound strategy:
Truth boundary:
Production simplification rule:

Lead with the strongest result when it is legible without setup, then return to a credible starting state. Organize chapters by user outcome or proof question, not by toolbar location. Require each chapter to leave visible accumulated state or decisive new knowledge.

Write the native interaction spine before any title, mockup, or compositing:

`real starting state → user input → native product response → consequential result`

For software demos, show the actual CLI, application, host integration, API consumer, or generated artifact named in the proposition. Evidence generated backstage and retyped into a presentation layer does not count as native use. Target at least 60% native product surface, place the first meaningful product action within five seconds, and keep explanatory/title surfaces below 20% unless the medium makes those ratios inapplicable and the plan records why.

Write one beat for each meaningful tactic, product action, reveal, consequence, or attention shift. A click is not a beat unless it changes the proof. Pair narration about value or consequence with an observable action; do not read the interface aloud.

Treat beats as actions and revelations, never equal time boxes. Record multiple observable events inside a longer beat. Default to no more than three seconds between visible or audible events for a promotional demo; a motivated hold is the only exception.

Save the plan as `beat-plan.json` using [artifact-contract.md](references/artifact-contract.md), then run:

python3 <skill-dir>/scripts/validate_demo_plan.py <demo-dir>/beat-plan.json

Fix plan failures before recording. Do not hide gaps in post-production.

Prepare and capture

1. Build a disposable, repeatable starting state. Preserve user data and existing recordings. 2. Prefer repository-native APIs, scripts, fixtures, and automation over manual UI control. Use a browse