build-product-demo

# 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:

```text
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:

```bash
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