Issue to Demo

Turn a feature idea into a demo that is short, obvious, and easy to ship.

When to use

• A feature exists in code or in a spec but not in a presentable demo.
• A maintainer wants better screenshots, GIFs, or walkthroughs for a release.
• A team needs a 30 to 60 second demo before launching publicly.
• A project has too many features and needs one clear hero story.

Workflow

1. Isolate the wow moment.

• Pick the smallest user journey that proves the feature matters.
• If there are multiple features, choose one hero path instead of showing everything.

1. Define the demo path.

• Start state
• Trigger action
• Visible change
• Final payoff

1. Design proof assets around that path.

• Screenshot sequence
• GIF or short video beat list
• CLI transcript if the product is terminal-first
• README snippet that explains the before and after

1. Remove friction from the story.

• Cut setup steps that do not add meaning.
• Avoid edge cases in the primary demo unless the user asks for them.

1. Hand off a reusable package.

• The output should be usable by a founder, engineer, or designer without translation.

Expected Deliverables

• A 30 to 60 second demo outline
• A shot list for screenshots or a GIF
• Suggested captions or narration
• A README-ready example section
• Risks that could make the demo confusing

Output Style

• Show one thing clearly before showing many things quickly.
• Bias toward visible user outcomes.
• Keep the demo honest and technically feasible.

References

• Read references/demo-blueprint.md when you need a reusable structure for demo beats, visual assets, or narration.