From bc067d239ca1af44b5f81729c43cf824eb1c65b1 Mon Sep 17 00:00:00 2001 From: Scott Scoble Date: Sat, 9 May 2026 07:11:50 -0700 Subject: [PATCH] =?UTF-8?q?docs:=20Show=20HN=20demo=20script=20=E2=80=94?= =?UTF-8?q?=202-min=20terminal=20recording=20walkthrough=20for=20launch=20?= =?UTF-8?q?day?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/show-hn-demo-script.md | 165 ++++++++++++++++++++++++++++++++++++ 1 file changed, 165 insertions(+) create mode 100644 docs/show-hn-demo-script.md diff --git a/docs/show-hn-demo-script.md b/docs/show-hn-demo-script.md new file mode 100644 index 0000000..842b8bc --- /dev/null +++ b/docs/show-hn-demo-script.md @@ -0,0 +1,165 @@ +# Show HN Demo Script — Speckl + +**Purpose:** 2-3 minute terminal recording for the Show HN post (May 12-13) +**Format:** Terminal screen recording (asciinema or screen-capture GIF) +**Goal:** Show "spec in, 5 auditable artifacts out" in under 3 minutes + +## Pre-flight (before recording) + +```bash +# Verify compiler is clean +cd ~/speckl/compiler +npm test # should show 41/41 passing + +# Clear output +rm -rf out/demo-script +``` + +## Scene 0: Title Card (5 sec) +Show `~/speckl/examples/` directory listing. Voiceover or text overlay: +> "Speckl is a judgement transport utility for AI-generated specifications. Let me show you what happens when you compile a spec." + +## Scene 1: The Spec (15 sec) + +```bash +cat examples/ToggleSwitch.speck +``` + +Narrate: +- "This is SpeckDL — a specification language designed for both humans and compilers." +- "It has types, records, state variables, actions with guards, preconditions, and postconditions." +- "This is the same ToggleSwitch you'd write in TLA+, but with one difference: it compiles." + +## Scene 2: One Command, Five Artifacts (20 sec) + +```bash +node dist/index.js examples/ToggleSwitch.speck -o out/demo-script +ls -la out/demo-script/ +``` + +Narrate: +- "One command. Five artifacts." +- "A PROV-O provenance graph, a TypeScript state machine, WebAssembly, a CycloneDX BOM, and an SPDX BOM." +- "Every one of these is independently auditable." + +## Scene 3: The TypeScript (20 sec) + +```bash +cat out/demo-script/ToggleSwitch.ts +``` + +Narrate: +- "This is production-ready TypeScript generated from the spec." +- "The state machine is a class with typed methods for every action." +- "Guards become assertions. Actions become mutations." + +## Scene 4: TypeScript Compiles Clean (10 sec) + +```bash +npx tsc --noEmit out/demo-script/ToggleSwitch.ts +echo "Exit code: $?" # should be 0 +``` + +Narrate: +- "It compiles with zero errors. You could import this into any TypeScript project right now." + +## Scene 5: The WASM (15 sec) + +```bash +head -40 out/demo-script/ToggleSwitch.wat +``` + +Narrate: +- "It also compiles to WebAssembly. This is the exact same spec — same toggle logic — but now it runs in any browser or edge runtime." +- "One spec, multiple targets. That's the power of compiler-level provenance." + +## Scene 6: The Provenance Graph (15 sec) + +```bash +python3 -m json.tool out/demo-script/ToggleSwitch.prov.jsonld | head -30 +``` + +Narrate: +- "Every artifact links back to the original spec through a W3C PROV provenance graph." +- "This is what NIST SA-11 calls 'human-in-the-loop for automated outputs.'" +- "You can prove what ran came from what you wrote." + +## Scene 7: The BOMs (15 sec) + +```bash +cat out/demo-script/ToggleSwitch.specbom.cdx.json | head -20 +echo "..." +cat out/demo-script/ToggleSwitch.specbom.spdx.json | head -20 +``` + +Narrate: +- "And you get two machine-readable bills of materials — CycloneDX and SPDX." +- "This means your compliance team can import Speckl's output directly into their existing toolchain." + +## Scene 8: TigerBeetle (15 sec) — CONDITIONAL + +Only include if engineering#9 + #11 are fixed by launch day: + +```bash +node dist/index.js examples/TigerBeetleLedger.speck -o out/demo-tiger +npx tsc --noEmit out/demo-tiger/TigerBeetleLedger.ts +echo "Exit code: $?" # should be 0 if bugs fixed +``` + +Narrate: +- "And it scales. Here's a naive TigerBeetle port — a double-entry ledger with 7 actions, 5 preconditions, and 4 postconditions." +- "Zero TypeScript errors. Production-ready from a spec." + +If NOT fixed by launch day, skip this scene. Instead show: + +```bash +cat examples/TigerBeetleLedger.speck | head -40 +``` + +Narrate: +- "And here's what we're working on next: a full TigerBeetle-style double-entry ledger. Spec written, compilation in progress. Follow the repo for updates." + +## Scene 9: Call to Action (10 sec) + +Show the repo URL and landing page: + +```bash +echo "github: https://os.scoble.me/forgejo/sscoble/speckl" +echo "mirror: https://codeberg.org/sscoble/speckl" +echo "site: https://speckl.scoble.me" +echo "spec: speckl.scoble.me#try-it — paste a spec and see output" +``` + +Narrate: +- "Speckl is MIT-licensed and open source. The whitepaper is in the repo. I'd love your feedback." + +## Recording Tips + +1. **Use asciinema** for terminal recording — it produces lightweight `.cast` files that can be embedded or converted to GIF + ```bash + asciinema rec speckl-demo.cast + ``` +2. **Or use terminalizer** for a styled GIF with a config file +3. **Keep it under 3 minutes** — Show HN attention spans are short +4. **No audio needed** — terminal text + captions work better for HN +5. **Paste the asciinema link or GIF** directly in the Show HN post body + +## Alternative: Static Screenshot Flow + +If terminal recording is too much setup, use 5-6 screenshots in sequence: +1. The `ToggleSwitch.speck` source +2. The `ls` output showing 5 generated files +3. A snippet of generated TypeScript +4. The `tsc --noEmit` clean exit +5. A snippet of the PROV-O JSON +6. The landing page with "Try It" CTA + +Less impressive than a recording, but zero setup time. + +## Post-Launch + +After Show HN goes live, share the demo recording on: +- Twitter/X with the HN link +- LinkedIn with a short writeup +- r/programming (Reddit) +- Speckl landing page (embed the asciinema player)