presentation

# Presentation Turn a technical specification into an interactive, persuasive web deck — the kind at iii.dev/roadmap/. The output is a **content layer** inside the repo's roadmap base (the shared component library, gallery, and markdown spec viewer that build every deck into one static site — Astro routes of the site package in iii, a standalone Vite project in other repos): 1. helps engineers **understand** the spec — the architecture is a navigable map, not prose; 2. is **interactive** — steppable diagrams, a selectable system map, live toggles; interactivity is what makes it stick; 3. reads like **marketing** — it argues the *why*. if no one is convinced the work should happen, the spec has not done its job; 4. is **build-in-public ready** — each deck ships as a static page at `/roadmap/<slug>/`, safe to share. ## Comparable to A product launch microsite generated from an RFC. Stripe-doc clarity meets a keynote narrative, in a monospace drafting-sheet style. ## Activation ### Use For - generating an interactive deck from a tech-spec directory - refreshing or extending a presentation already generated by this skill ### Do Not Use For - writing the spec itself — use `/tech-spec` - static slide exports (pdf / keynote) — use a slide tool - general UI work unrelated to a spec — use `/design` ## Load First Read these before building (they are the law — do not re-derive them): - `reference/design-system.md` — the locked tokens, type, motion, layout - `reference/archetypes.md` — the interactive slide library + how to pick one - `reference/component-standards.md` — deck-local vs promoted components, the promotion checklist, the registry format - `reference/narrative-framework.md` — the persuasive arc + outline rules - `reference/quality-bar.md` — the checklist to self-verify before finishing - `reference/hosting.md` — the two-tree layout, the pairing contract, frontmatter registration, and deploy - **per repo:** `<base>/COMPONENTS.md` — the live registry of that repo's shared components. It may exceed the bundled catalog; when it and `reference/archetypes.md` disagree, **the repo registry wins**. The skill bundles two scaffolds: - `template/` — one deck's **content layer** (App, sections, pages, content data, the spec-docs glob). Copy it per spec; everything visual comes from the base's shared `src/` via the `@lib` alias. You generate only content. - `base/` — the whole per-repo presentations site: the shared component library + design tokens, the gallery, the md-only spec viewer, and the build glue (`build.mjs`, `vite.config.ts`, one `package.json`). Copy once per repo (in iii it already lives at `website/roadmap/`); per-deck runs never modify it except **additive component promotion** per `reference/component-standards.md`. ## Progress Updates Emit one short line before each phase: `ingesting spec` → `reading the component registry` → `proposing outline` → `scaffolding` → `generating slides (k/N)` → `registering spec frontmatter` → `verifying`. ## Workflow Phases are gated. Do not skip Phase 2's approval or Phase 5's verification. ### 0. Resolve inputs - The argument is a tech-spec directory: `<repo>/tech-specs/<slug>/` — **markdown only** (README.md + domain docs; frontmatter in README.md). If given a path elsewhere, resolve into the spec tree or ask. - The **slug is the spec directory's basename** (e.g. `2026-06-21-devexp` — `YYYY-MM-DD-<name>`; the day prefix orders the roadmap timeline). It is the deck directory name AND the URL segment — the pairing contract in `reference/hosting.md`. Fix it now and use it everywhere; never prettify it. - Resolve the **base project**: read `<repo>/tech-specs/README.md` — the pointer names the base dir (in iii: `website/roadmap/`). Fallback: search for a dir containing both `COMPONENTS.md` and a shared `src/`. Detect its shape: - **integrated base** (shared `src/` + `scripts/manifest.mjs`, no package.json or build.mjs of its own — iii's shape: the site's Astro pages at `website/src/pages/roadmap/` render each deck's `src/App.tsx` as a React island via the base's `src/DeckHost.tsx`; deps live in the `iii-website` package) → use it, and scaffold content layers only; - **standalone base** (`build.mjs` + own `package.json`, one `index.html` per deck — the `base/` snapshot's shape) → use it; - **absent** → first run in this repo: pick the location with the user (default `website/roadmap/` when `website/` exists, else `roadmap/` at the repo root) and scaffold it in Phase 3; - **legacy layout** (`tech-specs/build.mjs` + `_gallery/` — per-deck standalone projects) → stop and offer the port procedure in `reference/hosting.md` before generating anything new. - Output location is `<base>/<slug>/`. If it exists and is non-empty, ask: overwrite, update in place, or abort. **Never write a non-markdown file under `tech-specs/`.** - Detect the install mode: workspace (repo `pnpm-workspace.yaml` lists the base) vs standalone (`pnpm install --ignore-workspace` inside the base). ### 1. Deep ingest (read, do not skim) - Read the spec `README.md` in full first: thesis, architecture, principles, cross-cutting contracts, migration overview. Note whether it already has a frontmatter block (title/tagline/date/tags/status). - Read every domain doc. For each, capture: the one load-bearing phrase, the pain it removes, the mechanism, any schema/fields, any sequence/lifecycle, any numbers, any honest trade-off. - Build a **content inventory** (architecture, protocol/wire contract, lifecycle, state model, config schema, security, migration, …). This is the raw material for archetype matching. **1b. Component awareness (before planning).** Read `<base>/COMPONENTS.md` end to end and list `<base>/src/components/{schematic,diagrams}/` + `src/hooks/`. The registry is the live catalog for this repo and supersedes the bundled `reference/archetypes.md` where they disagree. **Reuse-first mandate:** a slide may get a bespoke visual only after the catalog demonstrably has no fit for its content shape. Name any planned new component in the Phase 2 outline, marked `local` or `promote` (see `reference/component-standards.md`), so the user approves it at the same gate. ### 2. Narrative plan — THE GATE - Apply the arc in `reference/narrative-framework.md`. Produce a deck outline: an ordered slide list, each with `{ title, archetype (or reused registry component), the single claim, source section(s), the concrete data it pulls, interactivity, new component: <Name> (local|promote) — only when nothing fits }`. Include candidate deep-dive pages. - Derive the hero line + three-value subhead + stat strip. Choose the wordmark label. - **Present the outline to the user for approval/edits before scaffolding.** This is the cheapest place to turn a dry spec into a story. Skip only if the user explicitly says "just build it". ### 3. Scaffold (mechanical) **The deck:** - `mkdir -p <base>/<slug>/` and copy `template/` into it — in an **integrated base (iii)** copy `template/src/` only and skip `index.html` and `src/main.tsx` (the site's `[slug]/index.astro` route provides the document shell and mounts `src/App.tsx`; the page title/description come from the spec frontmatter). - Substitute the `__SPEC_MD_GLOB__` literal in `src/spec-docs.ts` with the computed relative path from `<base>/<slug>/src/` to `<specs-dir>/<slug>/*.md` (in iii: `../../../../tech-specs/<slug>/*.md`); in a standalone base also `__TITLE__` / `__DESCRIPTION__` in `index.html`. - **No per-deck install, no per-deck config, no lockfile.** Ensure deps once: workspace mode → `pnpm install` at the repo root (only if the base's deps are missing); standalone mode → `pnpm install --ignore-workspace` in `<base>` (commit the generated lockfile). **Registration:** write or update the YAML frontmatter block at the top of `tech-specs/<slug>/README.md` (schema in `reference/hosting.md`): title + tagline from the approved hero, `date: YYYY-MM-DD` (day precision — the roadmap timeline orders and labels by it), 0–4 tags, `status: draft`. There is no central manifest — the build aggregates every spec's frontmatter, so this run touches nothing shared. If frontmatter already exists, update only the fields this run owns (tagline polish, status). **The base project** (first run in a repo only): copy `base/` into the chosen dir (never its `node_modules`/`dist`). Fill the identity once: `__REPO__` in `package.json`; the `__GALLERY_*__` / `__WORDMARK_LABEL__` / `__HERO_*__` / `__ATTRIBUTION__` / `__SITE_HOST__` tokens in `index.html`, `src/gallery/site.ts`, and `README.md`; write the `tech-specs/README.md` pointer. The gallery page is a **roadmap**: hero copy in roadmap voice (`__HERO_TITLE__` ≈ "what we're working on"; `__HERO_LEAD__` hints at the current priority and what already landed, without naming specs), and the spec list renders as a one-column timeline, newest first, grouped by month. In a workspace repo, add the base to `pnpm-workspace.yaml` **with user confirmation** (a repo-level file). Never touch `build.mjs`, `vite.config.ts`, tsconfigs, or `src/` beyond this copy. ### 4. Generate the content layer Edit only these — the write surface is `<base>/<slug>/**` plus the spec's frontmatter block (and an approved promotion): - `src/content/deck.ts` — `DECK_META.wordmarkLabel`, `NAV`, `FOOTER`. - `src/content/<topic>.ts` — the typed data arrays each archetype consumes (map nodes/edges/info, sequence lanes/steps, reveal stages, cli tracks, metrics, rows). Keep data here, out of components. - `src/sections/<Name>.tsx` — one thin section per slide: import the matching archetype from `@lib`, feed it data, wrap it in `<Section>`. Replace the example sections; delete `src/content/example.ts` and `pages/ExamplePage.tsx`. - `src/pages/<Name>.tsx` — deep dives via `@lib` `<PageShell>`. - `src/App.tsx` — wire the ordered `SECTIONS` array and the `PAGES` map. **The component protocol** (when a load-bearing concept has no fit in `COMPONENTS.md`): 1. **Default: build it deck-local** in `<base>/<slug>/src/diagrams/<Name>.tsx`, following `@lib/components/diagrams/SequencePlayer.tsx` conventions. 2. **Promote into `<base>/src/components/` only when all three hold:** (a) it is generic over its data — nothing spec-specific inside, everything arrives via typed props; (b) it maps to a recurring spec shape (a lifecycle, a tree, a timeline, a fan-out…) future decks will plausibly need; (c) it passes the checklist in `reference/component-standards.md` without deck-specific hacks. 3. A promotion = the component file **plus its `COMPONENTS.md` entry in the same change**. An unregistered shared component is a defect (the base's registry check warns — `scripts/validate-roadmap.ts` in iii, `build.mjs` standalone; strict mode makes it fatal). 4. Never fork a shared component into the deck to tweak it — extend it via additive, non-breaking props, or build a genuinely different deck-local one. **Modifying an existing shared component requires explicit user approval** (it re-renders every other deck). **Built-in spec viewer — do not delete.** Every deck ships the `#/spec` page: the template wires `spec-docs.ts` (the compile-time glob over the paired spec's markdown) into `@lib/pages/SpecPage` via `PAGES.spec`, and the shared `TopNav` renders the `spec` link. The shared markdown renderer strips the frontmatter block. It needs no per-deck content — leave the wiring in place. ### 5. Verify — THE SECOND GATE All commands run from `<base>`'s package (iii: `pnpm --filter iii-website <script>` from the repo root; standalone: inside `<base>`): - `pnpm type-check` — the whole roadmap project (shared src + gallery + every deck) must pass strict; fix every error. - The build must succeed with zero frontmatter-validation or registry-parity warnings — iii: `pnpm build` (the site build runs the roadmap contract checks and emits `dist/roadmap/<slug>/`); standalone: `node build.mjs --only=<slug>`. - `pnpm dev` in the background, then dogfood with the **`/browse` skill** (never `mcp__claude-in-chrome__*`): load `http://localhost:4321/roadmap/<slug>/` (standalone: `:5173/<slug>/`), click the map, run a stepper, toggle the theme, open a deep-dive, open `#/spec` and confirm every markdown file renders (mermaid fences live, no raw frontmatter). Zero console errors; no horizontal body scroll at 375px. - `pnpm build && pnpm preview`, then `/browse http://localhost:4321/roadmap/` (standalone: `:4173/`): the spec appears on the roadmap timeline in date order under its month, its card shows the frontmatter title/tagline/tags with the day marker in the timeline gutter, and clicking it lands on `/roadmap/<slug>/`. If the spec previously served the md-only viewer, confirm the deck replaced it at the same URL. - **If anything under `<base>/src/` was touched (a promotion): run the full site build** — a shared change must not break sibling decks. - Run `reference/quality-bar.md` end to end; fix anything red. ### 6. Hand off Report: the deck path (`<base>/<slug>/`), the dev URL, the slide list, which interactions are live, the frontmatter written, and any promoted components (with their registry entries). Offer to flip `status: draft` → `live`. Deploy is not a step: **in iii, merging to main ships everything via `.github/workflows/deploy-website.yml` to `iii.dev/roadmap/<slug>/`**; in other repos `dist/` is a portable static site for whatever CI they use. Do **not** commit, push, or configure hosting unless asked. Never run `vercel`. ## Rules - **The shared layer is law**: never edit `<base>/src/**`, the base's build glue (iii: `website/src/pages/roadmap/` and `scripts/validate-roadmap.ts`; standalone: `build.mjs` and `vite.config.ts`), tsconfigs, `package.json`, or the gallery in a deck run. Sole exception: additive component promotion under `reference/component-standards.md`, always paired with a `COMPONENTS.md` entry. - A deck run's write surface is `<base>/<slug>/**` plus the frontmatter block of `tech-specs/<slug>/README.md`. Nothing else. - `tech-specs/` holds markdown only. Never write a non-md file there; never create a `presentation/` directory inside it. - Reuse first: consult `COMPONENTS.md` before building any visual; the repo registry outranks the bundled catalog. - Slug = the spec directory basename, used identically as the deck dir and the URL. Never prettify it. `slug` is never a frontmatter field. - One claim per slide. Put depth behind a `<SpecSheet>` (`<details>`), closed by default — execs skim, engineers drill. - Ration the accent (success / active / CTA only). Lowercase copy; identifiers keep their casing. No em-dashes. No "robust / comprehensive / crucial / seamless / unlock". - Ground every claim in the spec. Keep one honest trade-offs/open-questions beat — honesty reads as credibility. - Quantify the win: use the spec's numbers verbatim; if you compute one, say so. ## Decisions Ask the user: the narrative outline (Phase 2, always); output location when occupied; audience tilt (execs vs engineers; default balanced); fonts offline vs CDN (default CDN); scope cap when a spec has many domain docs; first-run