Product Demo Builder

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 before selecting features or writing beats. Read production.md before recording, generating narration, or using deterministic fixtures.

Build the evidence inventory

Classify every candidate claim:

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, 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 browser or desktop controller only when the product proof genuinely depends on that surface and no lower-level route can execute it.
3. Use deterministic data only to stabilize inputs or external dependencies. Keep the real product path active and record the boundary in the plan.
4. Run a fast, silent rehearsal. Confirm selectors, commands, product results, duration, native-surface ratio, event density, and exit states before paying for narration or a full recording.
5. Audition narration with the actual language and script. Measuring duration is not an audition. If the agent cannot hear the sample, require a human selection or use a non-voice treatment instead of claiming the accent is approved. Voice labels and locale names are not evidence of accent, naturalness, or timing.
6. Record clean picture, UI/action sound, narration, and music as separable elements when practical. Retain raw evidence and logs.
7. If a production path fails, report the failure and repair that path. Do not silently substitute screenshots, fake progress, or a different capability.

Edit and diagnose pacing

For every cut, finish:

Cut from [state/action] to [new state/action] because the audience now needs to [learn/feel/locate/compare/anticipate].

Shorter is not automatically faster. Remove unexplained waiting, duplicated information, cursor travel with no consequence, and narration that finishes before the corresponding action begins. Preserve enough time to orient, see the action, register the result, and anticipate the next beat.

When diagnosing “slow” or “stuck” pacing, locate the first mismatch:

1. no new product or audience state;
2. action begins too late after narration;
3. action finishes but the result is not framed;
4. capture contains real processing with no readable status;
5. edit holds a redundant image;
6. audio or encoding creates apparent freezes.

Repair the mismatch instead of globally speeding up the video.