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