writing-deck-specs

name	writing-deck-specs
description	Use when defining the CONTENT of a slide deck or presentation for handoff to a separate rendering step (e.g. Claude Design) — turning meeting notes, a topic, or raw material into a per-slide content spec with diagram specs. Triggers include "build a deck/slides", "prep a talk", "spec the slides", "didactic technical presentation", or planning what each slide says before any visuals exist.

Writing Deck Specs

Overview

A deck spec defines what each slide says and shows — not how it looks. A separate renderer (Claude Design) turns it into the actual visual deck. The spec is the contract: precise enough that the renderer never has to guess, silent on styling it has no business deciding.

Core principle: content and narrative are decided here; pixels are decided downstream. Keep the two apart.

When to use

• Turning meeting notes, a topic, or raw material into a structured talk.
• Any time you'll hand slide content to a separate rendering step.
• Didactic / technical presentations where the order of ideas matters.

Not for: writing the rendering code, picking colors/fonts (that's the renderer), or one-off single slides.

A spec has two layers

1. Header — the framing that governs every slide.
2. Per-slide content — text + an optional diagram spec per slide.

1. Header (framing)

State these up front, before any slide:

• Objetivo — the one thing the audience should leave with.
• Audiencia — who they are and what they already know (sets the depth).
• Narrativa — the arc, chosen on purpose (e.g. what it does → how it scaled). Name it.
• Decisiones de alcance — the explicit rules: what you deliberately leave out and why (e.g. "no numbers on slides", "simplify dual-queue → one queue"). These prevent the renderer (and you) from drifting.

2. Ground the content in truth

Before speccing, verify claims against the real source — the repo, the data, the docs — not just the notes you started from. Notes are imperfect memory; the source is authoritative. When they conflict, the source wins (and say so).

Keep a "Hechos verificados" section: the confirmed facts that back the talk, with where each was checked. Park here the numbers and details that do NOT go on slides but that you'll want if someone asks. The slides stay clean; the spec stays honest.

3. Narrative principles

• Title-only flow test: read just the slide titles in order. Does the story flow with nothing else? If not, the structure is wrong — fix it before content.
• Anchor diagram + progressive reveal: introduce one core diagram once, then reuse it as the throughline — revealing pieces one at a time and highlighting the part in play. Give it named states (base / active / dim / +queue / +dial) so later slides layer onto the same picture instead of starting over.
• Bookend: plant an idea early, call it back at the climax. It makes the arc feel closed.
• Deliberate arc, deliberate cuts: every slide earns its place. If a slide has "a lot to say", it's two slides.

4. Per-slide format

Each slide is texto + an optional [SVG] block.

### Slide N — <short title>
- <terse line of what the slide says/shows>
- <one idea per slide; if it's two ideas, split the slide>
- [SVG] <diagram spec — see §5>

Convention: all non-text content is SVG. Text lines describe what is said; the [SVG] block describes what is drawn. Never put numbers on a slide unless a scope decision says so.

5. Diagram spec conventions

Describe a diagram so the renderer materializes it without guessing. Specify:

• Layout — horizontal chain / 2×2 grid / sequence diagram / before-after panels. Say which.
• Boxes — what each one is, with its short label.
• Arrows — direction and meaning (A → B, fan-out 1 → N, callback).
• Emphasis — what should pop, what should be dim/secondary.
• States — for an anchor diagram, the variant this slide uses.
• What NOT to include — kill detail the audience doesn't need yet (a forward-reference to a concept not introduced yet is the classic mistake).

Good: "Pipeline of 7 boxes left-to-right, arrows between each; box 6 highlighted blue, the rest dim; a queue glyph in front of box 6 only."

Bad: "A nice diagram of the pipeline."

Handoff & security

• The spec is the handoff. When you pass it (or a prompt built from it) to the renderer, it must be self-sufficient.
• Never put secrets or sensitive values (keys, DB URLs, tokens) into a spec, an example, or a renderer prompt. Reference them by name only.

Common mistakes

Mistake	Fix
Speccing from notes without verifying	Check the source of truth first (§2).
Numbers leaking onto slides	Park them in "Hechos verificados"; state the no-numbers scope rule.
Forward-references in a diagram	List them under "what NOT to include" (§5).
One slide carrying two ideas	Split it.
Vague diagram spec	Name layout, boxes, arrows, emphasis (§5).
Deciding colors/fonts/layout in the spec	That's the renderer's job. Specify content only.