Demo Narrative

Demo Narrative

Overview

Produce a scripted, scene-by-scene demo flow with talking points, wow moments, fallbacks, and a seed-data checklist — before the live demo. Output is .forge/demo-narrative.md: the audience and goal, the one key insight the demo must land, the scene script, the fallbacks, the Q&A anticipation, and the dry-run checklist. Pairs with seed-data-and-fixtures (the data backing each scene) and gtm-strategy (the wedge feature the demo is selling).

When to Use

• A sales, investor, or partner demo is scheduled in the next 7 days
• A product walkthrough is being recorded
• A pitch deck is being built and the demo flow needs scripting
• The team has done "ad-hoc product walkthroughs" before and lost deals or stalled them

When NOT to Use

• Pre-product, no working software yet — use gtm-strategy and competitive-analysis instead
• A demo for an internal audience that has full context — informal walk is fine
• The user-facing surface isn't ready and the demo would expose work-in-progress

Common Rationalizations

Red Flags

• A demo scheduled in <48h with no dry-run done
• Lorem ipsum, "Test User", or all-now() timestamps visible in any scene
• No fallback plan if a live API call fails
• No identified wow moment — the demo is "let me click through the menus"
• Feature parade structure ("here's the dashboard, here's the settings, here's the reports")
• Demo length unbudgeted, no buffer for questions
• Slack/email/notifications visible on the screen sharing surface
• Screen recording or live demo without testing the network the demo will use

Core Process

Step 1: Define audience + goal

Write at the top of .forge/demo-narrative.md:

• Audience: who (role, seniority, prior context). What they care about (cost / speed / risk / status quo).
• Goal: the one decision you want them to make after watching. Examples: "agree to a pilot", "introduce us to the security team", "wire transfer for Q3 commit".
• Time budget: 30 min total → 18 min demo + 12 min Q&A. With 20% buffer.

Step 2: Identify the one key insight

The demo must land one insight — the audience-shaped reframe of the product. Examples:

• "Your team is spending 4 hours/week on this; we make it 4 minutes."
• "Every existing tool requires X to use; ours requires nothing."
• "The data you already have can answer Y in real time."

Write the insight as a single sentence. Every scene in the demo serves this insight.

Step 3: Write the scene-by-scene script

5-7 scenes. Each follows: setup → tension → wow → resolution.

Per scene, document: scene goal, setup talking track, tension, wow moment, resolution talking track, required seed function, fallback (recorded GIF or screenshot), and time budget. Example:

### Scene 3 — "The 4am page" (3.5 min)
Goal: show the runbook auto-resolving a paging incident.
Setup: "You've had a 3am page. The on-call gets out of bed, and..."
Tension: alert fires, walk through what an engineer normally does.
Wow: click "Auto-mitigate", service recovers in 8 seconds, show audit log.
Resolution: "A 6-hour incident compressed to one click."
Seed: seedDemoIncidentScene() — incident at 03:14:22 UTC, runbook-001 alert.
Fallback: if auto-mitigate fails live, switch to assets/demo-incident.gif.

Each scene ends with a transition that hands to the next. No "next, let me show you..." — every transition reinforces the insight.

Step 4: Identify fallbacks for every scene

For every live action:

• What can fail (network, API, browser, third-party dependency)
• The fallback (recorded GIF, prebuilt screenshot, narrated story)
• The trigger ("if the spinner runs longer than 5 seconds, switch to the GIF")

Each fallback is rehearsed during the dry-run. The audience never sees the switch.

Step 5: Write the seed data checklist

Cross-reference seed-data-and-fixtures. For every scene:

• The named seed function (seedDemo<SceneName>())
• The state the scene assumes (logged in as @demo-user, dark mode off, no notifications)
• The reset script (between scenes if needed)

Verify the seed runs cleanly in the demo environment within 48h of the demo.

Step 6: Prepare Q&A anticipation

List the top 10 questions the audience will ask, with prepared answers. Examples:

• "What about security/compliance?" → cross-reference security-and-compliance skill summary
• "How is this priced?" → cross-reference gtm-strategy
• "Who else uses this?" → 3 named reference customers if available; honest if not
• "What's your moat?" → cross-reference competitive-analysis

Mark questions that the demo-runner should not answer in the room and should redirect to a follow-up.

Step 7: Run the dry-run checklist

Within 24h of the demo:

• Demo runs end-to-end on the exact machine + network that will be used
• Every scene's seed data is loaded and verified
• Every wow moment fires correctly
• Every fallback rehearsed (intentionally trigger each failure mode once)
• Notifications, badges, Slack, email — silenced and hidden
• Screen sharing tested with the actual conferencing tool
• Demo fits in time budget with 20% buffer
• Demo-runner can articulate the one key insight without notes

Step 8: Header

Prepend a forge:meta header to .forge/demo-narrative.md (generated_by: demo-narrative, generated_at: <ISO 8601 UTC with Z>, depends_on: [.forge/seed-data.md] if .forge/seed-data.md exists else [] — paths only, never hashes, generated_from: {.forge/seed-data.md: <upstream content_hash AT generation time>} if seed-data exists else {}, content_hash: <sha256 first 8 of THIS file's body>). See forge-dependency-graph.

Verification

• .forge/demo-narrative.md written
• Audience, goal, and one key insight stated in one sentence each
• 5-7 scenes scripted with setup/tension/wow/resolution
• Every scene has a named seed function in .forge/seed-data.md
• Every scene has a fallback plan
• Top 10 Q&A items prepared
• Dry-run completed within 24h of the demo
• Zero lorem ipsum or "Test User" in any scene
• Demo fits time budget with 20% buffer