---
name: "developer_live_demo_design"
description: "Design a live technical demo that survives the stage: risk triage for every step, enterable checkpoints, a one command reset, an offline mode, a recorded fallback for every risky step, and a rehearsed runbook with a readiness gate. Use when planning a live demo, live coding segment, launch demo, keynote demo, or conference demo that runs in front of an audience, as opposed to recording a demo video."
---

# Developer Live Demo Design

## Purpose

A live demo fails in public, in real time, in front of the exact people it was meant to convince. This skill designs the demo so a failure costs a step, not the talk. The method has five parts that all have to exist before the first rehearsal: a risk register for every step, checkpoints the demo can enter cold, a one command reset, an offline mode tested with the network off, and a recorded fallback for every step that can break. It ships a plan checker and a rehearsal gate, because a demo plan nobody tested is a wish.

This skill is for demos performed live. For recording and editing a demo video, use demo_video_production. For a coding video or stream, use live_coding_streams. For talking through slides without a live system, use public speaking material instead.

## Workflow

### 1. Write the one idea and cut the demo to it

Write the single idea the demo proves, in one sentence, before building anything. Show the problem, show the change, show the proof. Every step that does not serve that sentence gets cut, however good it looks at your desk. Every extra step is one more place to break and one less minute for questions.

Open with the finished thing working. If the rest of the demo collapses, the audience has still seen the idea land once. Demo a real scenario, not a tour of features: pick one situation a user actually hit and build the whole demo around it.

### 2. Build the risk register

List every step in order with its minutes, what it depends on, whether it changes state, and its risk grade. The full template is in `references/demo-plan-template.md`.

Grade risk honestly:

- High: visible failure you cannot hide. Live deploys, new logic typed live, hardware, venue networking, third party services.
- Medium: failure is quiet or quick to redo. Local commands with variable output, data loads, slow builds.
- Low: local, deterministic, same result every run.

Two hard rules come straight from the register. Every high and medium step gets a written fallback before rehearsal starts, and every step that depends on anything outside your control (venue wifi, a cloud service, a vendor API) gets one too. A step with no fallback does not go live. It gets recorded, checkpointed, or cut.

Write the plan as a CSV and run the checker:

```
python3 bin/demo_plan_check.py examples/good-plan.csv --slot-minutes 15
```

Fix every error it reports. Treat its warnings as stage problems you have chosen on purpose, in writing, or fix them too.

### 3. Put a checkpoint in front of every risky step

A checkpoint is a state the demo can start from cold: a git commit per step, a demo branch beside the finished branch, a seeded data snapshot, a saved workspace. Each checkpoint needs a name, a state, an entry line you say while it loads, and one rehearsal entry from cold to prove it works.

Checkpoints change what a failure means. Without them, a step 4 failure means restarting the demo and hoping. With them, it means entering at step 5, saying the entry line, and keeping the story whole. Test that switching between checkpoints works and that every checkpoint state runs. An untested checkpoint is set decoration.

Cut typing risk the same way. Pre-type boilerplate as editor snippets triggered by short prefixed keywords, scoped to the demo editor. Type live only the lines that teach something. Everything else is a snippet, a paste you announce plainly ("this part is plumbing, here it is"), or a checkpoint that already contains it.

### 4. Build the one command reset

Write one script, for example `./demo-reset.sh 4`, that returns the demo to a named checkpoint. It runs with no prompts and no network, restores code, data, and running processes, is safe to run twice, and prints the checkpoint it restored so you can read success off the projector.

Rehearse the reset until it is one motion. On stage you get one reset attempt inside the debug cap below. A reset you have to think about is not a reset, it is a second demo.

### 5. Give the demo an offline mode and test it with the network off

Assume venue internet is absent, not slow. Keep everything the demo needs on the laptop: files, databases, dependencies, slides, fallback clips. If the venue network works, that is a bonus, never the plan.

The offline test is physical, not a setting you toggle in your head. Turn networking off on the presenter machine, run the whole demo end to end, and log every step that stalls, degrades quietly, or reaches outside. Each one gets a local replacement, a cached copy, a seeded stand-in, or a fallback. A phone hotspot is plan B for steps that truly need a network, and it gets tested in rehearsal too, not discovered on stage.

Use a demo project and demo data, never a live account with real customer data. Preload data that looks real. Sparse data makes working features look broken, and a real account adds privacy risk and surprise state you do not control.

### 6. Record the fallback for every risky step

Record each risky step as a clean clip at the same screen size and zoom you will use live, plus a screenshot sequence under it. Narrate the clip live when you use it. A clip played with its own recorded voice while you stand silent reads as a demo you could not do. Your live voice over the same screens reads as a presenter handling a bad room.

Store fallbacks on the laptop and on a USB stick, named to match the runbook, in step order. Rehearse the switch itself: which file, which click, what you say while it opens. An unrehearsed switch costs the minute the fallback was meant to save.

Order fallbacks as a ladder, cheapest first: reset and retry once, enter at the next checkpoint, narrated clip, screenshots, words and slides only. The full ladder is in `references/demo-plan-template.md`.

### 7. Write the runbook you will present from

One block per step: what to say, what to do, what output to expect, what to do if it fails, and the bridge line that covers the switch. The bridge line is written in advance for every step. Composing it mid failure, out loud, is the hardest writing job in presenting, and the runbook exists so nobody has to do it live.

Keep the runbook on a second screen or printed page. Set editor and browser zoom so the back row can read the screen; a 125 to 150 percent browser zoom is a proven working range. Bookmark every URL or open it in a tab in advance. Nobody types a URL live.

### 8. Rehearse against the gate, including a failure drill

Log timed, out loud, full runs in the rehearsal CSV. The gate in `references/rehearsal-scoring.md` requires at least 3 full runs, the last two finished within 10 percent of planned time, recovery from failure demonstrated and timed, and at least one failure drill where you force the worst step to break and take its fallback for real.

```
python3 bin/demo_plan_check.py examples/good-rehearsals.csv --rehearsals
```

Rehearse with people at least twice: a first run for feedback, reviewed step by step right after, then a later run with fresh viewers mixed in. A step that fails in three rehearsals gets demoted to a recording or cut. It has already told you what it will do on stage.

### 9. Run the stage protocol when it breaks anyway

It will break eventually. The protocol is decided now, not on stage:

1. Say what is happening. Name what you expected, what you saw, and what you are doing next. Silence is what loses the room, not the failure.
2. Take 30 seconds, no more, for the one reset attempt. Narrate while you run it.
3. Still broken: take the fallback ladder rung for that step, say the bridge line, and keep the talk moving. Do not debug in front of the audience. A fix found after five silent minutes costs more than the step was worth.
4. Fix the root cause after the session. On stage, your job is the audience's next five minutes, not the bug.

A worked plan that follows all of this, with its timing math and the drill that changed it, is in `references/worked-demo-plan.md`.

## Output Contract

A finished design delivers:

- The risk register as a plan CSV that passes `bin/demo_plan_check.py` with no errors at the real slot length.
- A checkpoint map: name, state, and entry line for every checkpoint, each one entered cold at least once in rehearsal.
- The one command reset script, tested twice in a row and once in the venue or a stand-in room.
- An offline run log: the full demo completed with networking off, with every external dependency replaced or given a fallback.
- Fallback clips and screenshot sets for every high and medium step, stored locally in runbook order.
- The runbook, one block per step, with a written bridge line for every step.
- A rehearsal log that passes the readiness gate, including one failure drill.

If any item is missing, the demo is not ready. Shrink the demo until the list is complete, rather than presenting a bigger demo with holes in it.

## Operating Rules

1. One demo, one idea. Steps that do not prove the idea are risk with no payoff.
2. No fallback, no live step. This rule has no exceptions for confidence, seniority, or "it worked this morning."
3. Never debug on stage past 30 seconds. Reset once, then take the fallback and keep talking.
4. Never count on venue internet, a live account, or a third party service being up. Test offline, present offline capable.
5. Narrate every fallback live. Your voice is what makes a recording still feel like your demo.
6. State lives behind one reset command. If returning to a known state takes typing, it will fail when you need it most.
7. Rehearsal runs are timed, out loud, and logged. Memory of a smooth run is not evidence.
8. Cut scope before cutting rehearsals. Three runs of a smaller demo beat one run of a bigger one, every time.
9. Every factual claim in the demo (speeds, counts, customer results) gets verified before the talk or framed as your own experience. No invented numbers on a slide, ever.