/presentation

name: presentation
description: >-
  Turn a tech-spec directory into an interactive, marketing-grade web
  presentation — built so engineers understand the design, the reader is
  convinced of the why, and the result is shareable in public. Use when someone
  wants a spec turned into a deck.

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