How to write a demo script that lives in your repo

Every demo script feels right the day you write it. Keeping one usable after the product changes is the hard part, and most guides skip that completely. The moment the product ships, something drifts: a label changes, a flow moves, a proof point goes stale. The fix is simple enough. Keep the script in the repo, next to the product code, so the same agent or engineer who changes the product can update the demo at the same time.

What a demo script must contain to stay usable after the product changes

The four parts that actually matter

A demo script that survives product changes has four sections, no more:

• Opening context — one or two sentences about the buyer's situation. Not your product. Their problem, their workflow, their friction.
• Problem cue — the specific moment of pain the demo is meant to fix. One sentence. If you can't name it, the demo has no job.
• Product beat — the sequence of product actions that resolves the problem cue. Each beat maps to a real product state: a screen, a click, an output.
• Closing action — what you ask the buyer to do next. One clear ask, not three.

That's the skeleton. Sales research from Corporate Visions consistently shows that demos tied to a specific buyer situation outperform product-tour demos, not because they are prettier, but because the buyer can see themselves in the story.

What to leave out on purpose

Feature inventory kills reuse. Every time you add a "and we also have..." beat, you create another thing that can break later. Same with internal jargon, since your team's names for things rarely match what the buyer sees on screen, and same with edge-case branches like "if they ask about X, we can show Y." Put those in a separate objection file, not the main script. The base script should be short enough that updating it after a product change takes under ten minutes.

Turn discovery notes into a demo script outline

What discovery notes should feed the outline

Not every note belongs in the script. The filter is simple: does this note describe something the buyer said they already feel, or something you want them to feel? Only the first kind belongs. Objection logs, call snippets, and interview notes are useful when they surface the buyer's own language, the words they used to describe the problem. Those words become the opening context and the problem cue. Everything else is background.

Knowing how to write a demo script that converts starts here: the script is written in the buyer's language, not yours.

The problem-solution-result arc

The arc is simple: name the problem, show the solution in action, name the result. Every good sales story runs on this spine, and your demo script should too. In practice:

• Problem: "Right now, your team is doing X manually, which means Y delay."
• Solution: "Here's the moment where [product] changes that." Then show it, don't narrate it.
• Result: "That means Z outcome for your team."

The arc keeps the script from turning into a transcript dump. If a beat does not fit into one of the three slots, it does not belong in this version of the script.

The one question your notes have to answer

Before you write the outline, answer this: what is the single buyer question this demo is answering? Not "does this product work?" That is too broad. Something like "can this replace our current approval workflow?" or "will it integrate with our existing data pipeline?" That question becomes the organizing principle. Every beat either moves toward the answer or gets cut.

Before (raw notes): "They mentioned slow approvals, too many Slack threads, no audit trail, wants SSO, asked about pricing."

After (outline): Opening: slow approvals. Problem cue: approval request buried in Slack. Product beat: approval flow with audit trail. Close: trial with their workflow imported.

Write the first demo moment so the product feels relevant fast

Start with the buyer's problem, not your setup

The first thirty seconds of a demo script decide whether the buyer leans in or starts checking email. The opening beat should name the friction the buyer already feels, not introduce your company, not explain the product category, not show a dashboard overview. "You're currently running approvals through Slack threads, which means no audit trail and no way to escalate without a DM chain." That sentence earns the next one.

Use one specific scene, not a summary of the whole product

Pick one moment: a dashboard with a specific state, a workflow with a specific trigger, an object on screen that the buyer recognizes from their own work. One sharp scene beats a product tour because it gives the buyer something to project onto. Stripe's documentation famously opens on a single code snippet, not an overview of everything Stripe can do. The same idea applies to a demo script. One concrete moment, shown well, does more work than five features mentioned briefly.

Make the first transition feel inevitable

The move from problem to product action should feel like a direct response, not a pivot. "Here's how that looks in [product]" is enough. No "great question, let me show you something" phrasing, no setup slide, no "before I show you the product, let me explain the architecture." Click to the thing. The script's job is to make that click feel like the obvious next move.

Map each demo script beat to real product behavior

Treat the script like a code path

Each beat in an interactive demo script should point to an actual product state. Not "we show the dashboard," but "we show the dashboard with an open approval request, three days overdue, assigned to the user's name." That level of detail is what makes the beat maintainable. When the product changes, you know exactly which beat to update because each beat names a concrete product state.

Where the script and the product must match exactly

Four places where a mismatch breaks trust immediately:

• Labels — if the script says "click Approve" and the button now says "Submit for review," the demo stalls
• Steps — if the script shows a three-click flow and the product now takes two, the presenter looks unprepared
• Outcomes — if the script promises "you'll see the audit trail immediately" and there is now a delay, the buyer notices
• Screens — if the script references a screen that was removed or renamed, the demo dead-ends

The before-and-after edit that proves the point

Product change: the "Approve" button is renamed "Submit for review" and moved to a side panel.

Script before:

Script after:

That is a thirty-second edit when the script is in the repo. It is a twenty-minute hunt when the script lives in a shared doc nobody owns.

Version a demo script when the product changes

How to branch the script without duplicating the whole thing

A repo-native demo script branches cleanly when the base file holds the shared arc and variant files hold only the changes. One base file: `demo-script-base.md`. Variant files: `demo-script-enterprise.md`, `demo-script-founder-pitch.md`. Each variant file imports the base arc and overrides only the opening context, the proof point, and the closing action. Nothing else changes. Stripe's codebase migration to TypeScript is a useful model here. They kept a single source of truth and migrated incrementally instead of forking the whole codebase for every use case.

What counts as a meaningful change

Not every product change forces a script update. The ones that do:

• A UI label the script names verbatim
• A flow that gained or lost a step
• A feature the script uses as a proof point that now works differently
• A screen that was removed, renamed, or moved

Cosmetic changes, like color, spacing, or icon updates, rarely touch the script. The test is straightforward: does the change affect what the presenter says or clicks? If yes, update the beat. If no, leave it alone.

How to keep old versions from becoming dead weight

Tag old script versions with the product release they match: `demo-script-v2.3.md`. Keep them in a `/archive` folder in the repo, visible for context but not in the active rotation. Anyone who pulls the current script gets the current version. Anyone who needs to understand why a beat changed can diff the archive. The habit takes two minutes per release and prevents the "which version are we using?" conversation from happening at all.

Make one demo script work for founders, sales, and product teams

Keep the core story fixed and swap the emphasis

A demo script template that works across audiences has a fixed spine — problem, product beat, result — and variable endpoints: the opening context, the proof point, and the closing ask. The spine does not change. The framing around it does.

Branch on intent, not on random preferences

Three branches that actually matter:

• Founder pitch — opens on market problem, proof point is growth or retention, close is "here's the access"
• Technical buyer — opens on integration pain, proof point is API behavior or data model, close is "here's the sandbox"
• Sales-led walkthrough — opens on the buyer's stated job-to-be-done from discovery, proof point is a customer result, close is "here's the trial"

Everything else is some version of those three. Do not create a new branch for every persona. You'll end up with twelve scripts that nobody maintains. PostHog's writing on internal tooling makes the same point about code organization: the more you fork, the more you maintain.

What the team should reuse verbatim

The problem cue, the product beat sequence, and the result statement are the parts that must stay consistent across presenters. These are the load-bearing facts: the buyer's problem, what the product does, what changes as a result. Presenters can adapt the opening context to their own voice. They should not rewrite the product beats. That is where drift starts.

Use AI coding agents to draft and maintain the demo script

What the agent should write first

The best division of labor is simple: the agent drafts the outline, the human sharpens the story. Give the agent your discovery notes and the product beat sequence, and ask it to produce a structured outline with the four sections named. The agent is fast at structure and slow at judgment. The opening context, especially the buyer language that makes the problem cue land, still needs a human who was on the call.

How Cursor or Claude Code fits into the edit loop

The practical loop for a code-owned demo script:

• Product ships a change
• Engineer or agent updates the relevant code
• Same agent gets a prompt: "Update `demo-script-base.md` — the Approve button is now Submit for review and lives in the side panel"
• Agent edits the beat, commits alongside the product change

The script and the product stay in sync because they live in the same repo and move in the same commit. No separate doc to remember, no Slack message to send, no manual sync.

Where AI helps and where it still needs a human

The agent handles mechanical updates cleanly: label changes, step-count changes, screen renames. It also handles variant generation well when the base script is tight. It does not handle judgment calls: which proof point lands for this specific buyer, whether the opening context is specific enough to earn attention, whether the closing ask matches where the buyer is in the process. Those decisions need someone who knows the customer. The repo holds the source of truth; the human supplies the taste.

Where Inkly comes in

The problem the script section above names, the demo drifting from the product the moment you ship, is the same problem that breaks the demo artifact itself. A script in the repo helps, but if the demo it drives is a recording locked in someone else's SaaS, you're still re-recording every time the product changes. The fix is the same for both: the demo should be code you own, living next to the product and updated by the same agent that updates the script.

Inkly is built on that idea. The demo is code, not a recording, so when the product ships, you re-prompt your agent against the existing demo code instead of recapturing every affected screen. The same three-prompt loop that drafts the demo also updates it and produces per-customer variants: prompt to create, prompt to update, prompt to produce variants. The script and the demo move together, in the same repo, on the same agent loop.

If you're already running Cursor or Claude Code to maintain your codebase, you already have the agent you need to maintain a demo that stays current.

FAQ

Q: What should a demo script include if I want it to stay useful as the product changes?

Four sections: opening context, problem cue, product beat, and closing action. Keep each one short enough that a product change only touches one or two lines. Scripts that are longer than one page turn into maintenance work fast.

Q: How do I turn discovery notes into a persuasive demo script without making it too long?

Use one filter: does this note describe something the buyer said they already feel? Only those notes belong in the script. Use the buyer's own language for the opening context and problem cue. Everything else, like feature inventory, edge cases, and internal jargon, goes into a separate reference file. The script should answer one buyer question, and anything that does not serve that question gets cut.

Q: What should I show first in a demo if the goal is to make the product feel immediately relevant?

Name the buyer's friction in the first sentence, not your product, not your company, not a dashboard overview. Then show one specific product moment that resolves that friction directly. One sharp scene gets more attention than a product tour. The first transition from problem to product action should feel like a direct response, not a pivot.

Q: How do I adapt one demo script for founders, technical buyers, and sales-led teams without rewriting everything?

Keep the spine fixed — problem, product beat, result — and create variant files that override only the opening context, the proof point, and the closing ask. Three branches cover most cases: founder pitch, technical buyer, and sales-led walkthrough. The product beats stay identical across all three.

Q: How do I branch a demo script so different stakeholders hear the right story?

Branch on intent, not on persona labels. Ask what this stakeholder is trying to decide. A technical buyer is deciding whether the product fits their stack, so the proof point should be a sandbox or an API call. A founder pitch audience is deciding whether the problem is real and the traction is credible, so the proof point should be a retention or growth metric. One base file, three variant files, each one overriding only the sections that change.

Conclusion

The script is not a note for one presenter. It is part of the product. Write the outline in the repo today, with the four sections named and each product beat mapped to a real product state. The next time the product ships a change, update the beat in the same commit. That is how to write a demo script that stays usable, not as a one-time writing exercise, but as a living artifact that moves with the product.