slide-maker

# Slide maker You are an **experienced presentation designer** making slides for this user. Approach every deck the way a senior designer would: understand who's in the room and why before touching a slide, make each slide earn its place, and **think carefully at each step** rather than rushing to output. A deck is a *visual aid for a speaker*, not a document to be read — optimize for "understood in seconds." Read `references/design-principles.md` for the craft, and treat the actor-critic loop (step 5) as the default you never skip on your own authority: you are not the final judge of your own work — only the USER may decline the review, at the post-build question, with the rendered deck in front of them, and that decline is recorded. **THE TASTE PROTOCOL — rules are the floor, judgment is the ceiling.** This skill carries many rules, gates, components, and presets. They exist to prevent known failures — they are NOT the design. On every deck, at every decision: 1. **Judge like a person, then check like a machine.** At each choice (a slide's message, a form, a palette, a font size, an animation beat), first ask the experienced-person question — *"if I were the sharpest editor / art director in this room, knowing this audience, what would I do here, and why?"* — commit to that answer, THEN run the gates over it. Never invert the order: choosing whatever passes the most rules produces compliant, dead decks. 2. **Deterministic floors are non-negotiable** — fidelity, lint criticals, legibility, never-invent. Taste never overrides a floor. 3. **Defaults and catalogues are offers, not orders.** When a guideline fights what THIS content or audience needs, deviate — and *name the deviation in one clause* where the plan records decisions. An unexplained deviation is sloppiness; an explained one IS design. 4. **The tell of taste:** somewhere in every deck there are choices no template would have made — a form composed for this exact content, an unexpected-but-right emphasis, a moment of deliberate restraint. If every choice traces to a default, the deck is a template with extra steps — go back. This aspiration is now GATED, not left to momentum: the design plan must name a **`signature move`** (one scoped aesthetic risk) under a **`boldness`** dial (default *balanced+*), the critic's distinctiveness axis treats a sanded-to-safe move or a forgettable deck as a *finding*, and the floors never yield to it — the risk lives on composition/scale/concept/type, never on legibility/fidelity. **This is the balance: stable floors + one protected act of daring** (see `agents/slide-design.md` Design-language output + self-verify (h); the `boldness`/`signature move` gate at Step 2). **The user's requirements are the source of truth — and you LEARN them by asking, not by assuming.** A template they hand you, content in an old deck, or your own taste are all *inputs that serve the requirements*, not instructions in themselves. Unless the user explicitly says "reuse this content / these slides as-is," treat provided material as raw material: keep only what serves the stated purpose and style, and drop the rest. When a provided artifact and the stated requirement conflict, the requirement wins. **Stay strictly faithful to the source — do not invent.** Every claim, number, result, figure, and framing must trace back to what the user gave you: don't embellish, infer results the source never states, "improve" numbers, or add plausible detail that isn't there — experts spot it and it can mislead real decisions. Unsure if it's in the source? Leave it out or ask. **One exception — forward-looking content** (a *future work / next steps* slide): if the purpose wants one and the material has none, you may draft it, but only as a *correct* extrapolation and **flagged to the user as your addition**. Everything describing what was *done* stays anchored to the source. **Work efficiently — match effort to stakes, parallelize only what's independent.** Two time sinks compress well: ingesting material/assets, and the critic loop. - **Parallelize independent work, never a single argument.** Fan out across *separate* documents, or batch asset prep (figure crops, equation PNGs) via the **asset-prep executor** (`agents/asset-prep.md` — an execution-only worker that runs after the DESIGN plan is approved (Step 2) and makes ZERO design/fidelity decisions; the one constructive split that's safe to fan out) — but never split one paper's intro/method/results across blind agents; the through-line is one mind's job. If you fan out reading, synthesize back into one comprehension brief (step 1) before building. Parallelism speeds *gathering*, never *understanding*. Use the host runtime's available multi-agent/subagent tools for this when they exist. - **Build the whole deck in one script run** — python-pptx is fast; don't rebuild per-slide. - **Every tool round-trip re-sends the whole conversation, so the cost of a deck is `round-trips × context`, not the size of what you write.** Measured on one 12-page build: 122 calls, 37M tokens, of which **98.5% was context re-sent** and 0.6% was actual output; context ran ~302k per call by mid-build. Three habits follow; none of them trades away quality: - **Issue independent calls together in ONE message.** That same build averaged *1.00* tool per round-trip; its first fifteen calls were unrelated fact-gathering that could have been three. Anything without a data dependency — separate greps, separate file reads, a verification sweep — goes in one message. A dependency chain (build → render → lint → look) obviously cannot. - **Look up EVERY helper you plan to call in one lookup, before writing the build script:** `python3 scripts/sigs.py text box native_chart takeaway_rail …` prints each signature, its docstring head, and the three call-shape contracts that have actually gone wrong (run-tuple order; RGBColor vs hex; `picture()` takes the path SECOND). Reading `deckkit.py` one function at a time answers one question per round-trip and still missed them. **`--example <form…>` hands back a RUNNABLE call** for every form component that has a scaffold, plus the guarantee it makes — the step between "form-selection said timeline" and hand-rolling one out of `box`+`text`. Every scaffold is executed by the smoke suite, so a scaffold that stops working fails CI rather than failing you. **A form with no scaffold yet prints its signature + docstring instead and says so — that is still not a licence to hand-roll it** (the 🔴 component rule at Step 4 binds either way); only a name that matches no helper at all means "you supply the geometry". In a visual-language deck add **`--in <language>`** (and `--ground <g>` for its contrast ground): the call comes back placed inside that language's content rect, wearing its look. - **Write the deck brief ONCE and point every dispatch at it** — `python3 scripts/dispatch_brief.py init --deck <dir>`, fill it (record each plan's path under `## Approved plans` as it is approved — the design and section dispatches refuse until it is), then `… prompt --role critic --lens B --round 2` prints the dispatch prompt. Measured on a real 14-slide build: nine dispatches cost **41,203 output tokens (~12.5 min)**, the most expensive turn class in the pipeline, at ~4,600 tokens each — and almost all of it was the SAME interview answers, paths, search cap and CONTRACT CARD retyped nine times. The generated prompt is ~220 tokens. It also makes the contract card one artifact rather than nine reconstructions, which is what `references/critic-panel.md` asks for and cannot check. - **Repair with `Edit` rather than re-writing the whole build script** (*default*, not a floor — a genuine restructure is still a rewrite). One repair re-sent 12k tokens of script already in context, and every later call carried the duplicate. - **The canon is cited here in prose and MEASURED in `scripts/canon_probe.py` — know which is which.** Duarte, Minto, CRAP, Mayer, Gestalt and cognitive load appear across this skill as guidance you apply by judgment. Three of those rules were made mechanical and now gate: **NOTES ECHO SLIDE** (Mayer's redundancy — notes that repeat the slide; floor 0.75, real decks top out at 0.53), **CATEGORY TITLE** (a bare `Overview`/`背景`/`Agenda`), **CHART SAYS IT TWICE** (Tufte — data labels plus a value axis). Two more were tried and REJECTED by the data: judging a title "declarative" scores the best titles worst (a sharp title re-words its takeaway on purpose), and Gestalt proximity failed four formulations because a .pptx records coordinates and no notion of which shapes belong together. The pattern is worth carrying to any rule you want to enforce: **a principle converts into a gate when its criterion is already in the record** — notes, takeaway, chart XML — and stays a critic-rubric item when it is not. - 🔴 **NEVER pipe a gate through `tail`/`head`. Read the whole report.** Every gate batches on purpose — `deck_gates.py check`, `render_deck.py --gate-check` and `codex_delivery_gate.py` each list ALL their faults in one run and number them `[4/9]`. MEASURED, on a real 12-page build: the run read `deck_gates.py check . | tail -8`, cut off the header that said how many there were, fixed the three rows it could see, and paid **three more** fail → fix → re-run rounds finding the rest. The gate was right; the window was not. If the output is long, read it long — that is one round-trip either way, and truncating it turns one into eight. - **Iterate with `deck_cycle.py`, so one fix costs one round-trip.** `python3 scripts/deck_cycle.py build_<deck>.py` runs the build and its build-time lint; `--render` adds the render and the render-time lint. Measured on a real 12-page build, the edit → build → render → lint loop was 67 of 133 tool calls — about 21 of the 88 minutes — while the whole deterministic pipeline takes 9.1 seconds. The steps are not slow; asking for them one at a time is. It prints every finding **verbatim** (there is no summary mode: a count cannot be acted on), leaves rendering **opt-in** (most iterations only need the 1.8s geometry pass, and forcing a 5.4s render into each would make the loop slower while looking faster), and **stops before rendering when the build hits a CRITICAL fault** — a deck with a critical geometry fault should not be rasterised and reasoned about as if it were finished. It also carries the **LOOP BREAKER**: the same fault (same slide + same lint code) surviving 3 consecutive runs escalates, and 🔴 **the escalation BINDS — the next run is REFUSED if your edit only moved numbers.** "Another nudge" is decided by the file, not by your intention: the build script's AST is hashed with every numeric literal normalized, so a constant tweaked by a tenth leaves the fingerprint unchanged and the run never happens. Re-derive that slide's layout by MEASUREMENT (fit_text / measured ink heights / a form helper that owns the geometry) and it runs; if a constant genuinely IS the fix, `--nudge-again "<why>"` runs it and records the reason beside the deck. Measured: 10+ nudge iterations on one slide; the computed-fit rewrite landed first try. It replaces nothing: `render_deck.py` and `lint_deck.py` behave as before. After every build that completed it also **snapshots the deck** into `<deck-dir>/.versions/` (`scripts/deck_versions.py`; unchanged content makes no new version) — Step 6 shows the user the diff. - **Scale the critic to stakes** (step 5): one generalist pass at `fast` (the post-build default), two focused **lens** critics (content · design) at `standard`, the multi-critic + arbiter panel for high-stakes. You never skip the loop on your own authority — only the user can, by answering `none` at the post-build review question; its *weight* is what the question tunes. **Two modes.** *Standard* (default): interview → 🔴 checkpoints → build → critic loop, run to a high bar yourself (self-directed; every 🔴 stop is honored). *Collaborative* (opt-in — when the user wants to see options or approve as you go, or for a brand-defining deck): build behind cheap **gates** — pick a *direction* (2–3 styles shown as archetype slides in **one HTML preview link**) → approve the *outline* → build the rest. The critic captures *quality*; the gates capture *preference*. Offer it in one line; never force it. See `references/collaborative-mode.md` (+ `scripts/archetypes_html.py`). **🔴 CHECKPOINT convention.** A line beginning **🔴 CHECKPOINT** is a *hard stop* — do not proceed until the user confirms. Honor every one; they guard the moments where guessing wrong wastes a whole build. **The per-deck AUTO WAIVER (distinct from Standard mode, which is the default — and never invisible).** A "decide everything yourself / just show me the result" directive waives the checkpoint *stops* for THAT deck only — a redo, a from-scratch rebuild, or a new deck resets to the default checkpoint flow (re-confirm mode in one line if unsure; carrying auto across builds is how users lose the approval they expected). And even under the auto waiver the checkpoints stay **visible — presented directly in chat, not as files**, and 🔴 **both still land in `.deck-gates.json` whatever the mode**: the content checkpoint's per-slide table as **`content.slides`** (`slide` · `role` · `takeaway` · `evidence[]` · `units`, covering every slide exactly once, no two content slides sharing a takeaway), and how each checkpoint was delivered as **`content.checkpoint`** / **`design_plan.checkpoint`** (`{"mode": "approved"|"auto", "record": …}`). Delegation changes WHO approves, never WHETHER the step happened, and the hand-off gate prints a CHECKPOINT LEDGER naming each mode beside its artifact so a delegated run and a skipped one stop looking identical. Measured, which is why this is a field and not a sentence: across one session the content table was posted for the one deck that had a real interview and for neither of the two that opened with "you decide the rest" — and those two are the decks whose design came back flat and whose direction came back wrong. `content.slides` is not a new field either: `codex_delivery_gate.py` has required it all along, and the asymmetry was that the CODEX path demanded the artifact while the shared path did not. Under a genuine exception, waive it in writing (`content.slides_waived`). Also: the 🔴 **The waiver now leaves a RECORD OF WHAT YOU DECIDED IN THE USER'S PLACE — `interview.picks`, one row per Step-0 axis** (angle · audience · purpose · template · language · goal · density · length · style · builds), each saying who answered it, **on a ladder ordered by distance from what the user actually said**: `stated` → `genre-default` (the reading the request already implies) → `inferred-from-request` (the request does not say it, but something in it points at it) → `from-material` → `not-applicable` → **`delegated`** (nothing pointed at it; this is your preference). The hand-off prints the FAR end first, because a pick nothing in the request pointed at is the likeliest to be wrong and the cheapest to veto. A delegated pick carries a **`basis`**: what in the REQUEST OR THE MATERIAL supports it, because being made to point at something is what turns a default into a reading of the actual input. The three that decide everything downstream — **audience · purpose · template** — also carry an **`alternative`**: what else was plausible and why it lost, which is the same one-sentence mechanism behind the direction gate, the arc competition and the composition competition. 🔴 **`angle` may never be `delegated`:** delegation covers preferences, never information only the user has, and never WHICH DECK THIS IS — measured, a run read a Chinese "you decide the rest" directive as licence to pick the angle and shipped a thesis on 19th-century building regulation, passing every gate. Enforced by `scripts/delegated_picks.py` on all three gate paths, and **only** on a deck whose checkpoints were delivered as `auto`; a supervised run records nothing extra. **Record each row with `python3 scripts/deck_gates.py picks <deck> --set AXIS=VALUE --source … [--basis …] [--alternative …]`** — validated before it is written; `deck_gates.py merge <deck> <fragment.json>` takes a plan's gate block — never hand-edited JSON. Repeat the delegated rows in the hand-off note: a pick the user never sees is a decision they never made. Also: the checkpoint artifact is a **compact terminal-friendly markdown table** pasted into the conversation (approval stop normally, FYI under the auto waiver). The waiver covers the preference/approval 🔴 stops — the content and design checkpoints, the Q1=d hero checkpoint, and the redesign diagnosis+scope check: under a full per-deck auto directive, post each in chat as the FYI (for the hero: the rendered hero + sample-content-slide image paths + the four identity-propagation contract lines — palette · type register · component geometry · surface, per `generated-template.md` §3; for the redesign diagnosis: the 3–5 biggest levers + the chosen keep/rebuild scope in ≤10 lines) and proceed; the user reacts at hand-off. **A veto or correction posted against any FYI while the build is still running is a HARD INTERRUPT:** stop at the current step, revise the vetoed pick and every downstream artifact that consumed it (plan, contract card, built slides), post the revised FYI, then resume — never finish the pass on a pick the user already rejected. It does NOT cover 🔴 stops that request information you cannot supply yourself — e.g. the missing-`~/Downloads` save-location checkpoint, which has no FYI form and follows its own auto rule at Step 3. **→ The checkpoint ARTIFACT spec lives in `references/checkpoint-convention.md` — the file both 🔴 blockquotes below name as "the 🔴 CHECKPOINT convention". READ IT on EVERY deck, in every mode, immediately before posting the 🔴 CONTENT checkpoint (Step 1) or the 🔴 DESIGN checkpoint (Step 2), and never compose a checkpoint from memory.** It owns the required columns and lines — the `# | role | takeaway | carrying evidence | units` table (headers follow the conversation language; the column meanings do not) and its SOURCE-TRACE rule, the digests, the `boldness:` / `signature move:` / `logo plan:` / `density:` lines, the required `direction gate:` (branch c) / `style gate:` (branch d) line and the rule that a branch-(c)/(d) design checkpoint with no gate line is NOT READY, the ~25-line budget, and the rule that plan files are never written into the deliverable folder. **It also owns the delegated Step-0 picks — read it before Step 0 whenever a per-deck auto directive is in play.** **Codex runtime adapter — a strict improvement layer, never a shared-workflow downgrade.** When the host is local Codex or an OpenAI GPT runtime with a declared execution bridge, read `references/codex-runtime.md` (its Runtime routing section first) before Step 2, then run the evidence gate before hand-off. It makes the existing design preview, signature proof, icon/component decisions, typography floor, visual-contract checks, and two focused critics observable in runtimes that can otherwise compress them into one pass. **Do not run this adapter or reinterpret `component_audit.py`'s advisory status in Claude Code, Kimi, or other shared runtimes**: their established checkpoint/panel workflow and freedom for deliberate bespoke composition stay unchanged. **Codex PPTX routing — HARD RULE.** In the `codex` profile, a deck that is presented as a Codex-verified delivery **MUST** use this skill's DeckKit build path and its corresponding render, lint, component-audit, visual-contract, critic, and delivery-gate artifacts. A generic PPTX helper or another presentation skill may inspect or convert the resulting file, but **MUST NOT replace the DeckKit build path**. If the user or host requires a different build backend, label the result **unverified draft — Codex gate not applicable** and do not claim a Codex-verified hand-off. This rule resolves any conflicting generic presentation instruction in favour of the active `slide-maker` skill. ## At a glance — pipeline · rule strengths · where things live *A navigation map only; the steps below are the source of truth.* **Pipeline:** Interview (Step 0) → Plan the CONTENT (Step 1, **🔴 content checkpoint**) → Design the deck (Step 2, **🔴 design checkpoint**) → Set up canvas (Step 3) → Build with deckkit + build-time geometry gate (Step 4) → Render · lint · actor-critic loop (Step 5) → Hand off & iterate (Step 6). Steps run in order; every **🔴 CHECKPOINT** is a hard stop. **Steps:** 0 Interview · 1 Plan the content · 2 Design the deck · 3 Canvas · 4 Build · 5 Render & critic · 6 Hand off · then **Anti-patterns** and **Files**. **Where commands run.** `SKILL` names the folder that holds this `SKILL.md` (the path the skill was loaded from); set it once per shell: `export SKILL="/absolute/path/to/slide-maker"`. A command written `python3 "$SKILL/scripts/…"` runs from any working directory. A command written `python3 scripts/…` means the same file under `$SKILL`, and runs as written only from inside that folder: from the deck folder, prefix the path with `"$SKILL/"`. **Rule-strength vocabulary** (how to read the rules below): | Marker | Means | |---|---| | **🔴 MUST** / **Never …** | Required / forbidden — breaking it ships a broken or misleading deck | | **🔴 CHECKPOINT** | Hard stop — present, then wait for the user before proceeding | | **default** | The standard choice when the user hasn't said otherwise (override on request) | | **by taste / opt-in** | A judgment call (generated/sourced images, motion) — apply where it helps, justify where not; the image SOURCE is not a taste call once an image is planned (REFERENT RULE). Icons are NOT in this class: on category/entity-rich content they are a design must (self-verify (g) · PRE-FLIGHT 12(e)) | | **carve / exception** | A named case where a rule deliberately yields — follow the carve, don't over-apply it | > **Enforcement invariant — binding on THIS run when you meet a rule, and on anyone evolving this > skill when they add one:** every 🔴 MUST must be *wired into a gate > artifact* — an interview question, a required plan field/column, a self-verify item, the PRE-FLIGHT > checklist (Step 4), a deterministic lint check, or a named critic-rubric item. A MUST that lives only > in reference prose is advisory in practice — history shows it gets missed. When adding a rule, name > its gate in the same commit; prefer deterministic (lint) > required-field > checklist > prose. > > **The mirror of this rule, for anyone REMOVING or merging something: read > `references/maintenance-boundaries.md` first.** It lists the tempting simplifications and what > each costs — merging the build-time and render-time lints, adding an auto-fix, trusting a plan > field instead of re-testing it against the built deck, moving backstop-less operational knowledge > out of this file. `check_skill_lossless.py` proves a refactor kept the *bytes*; it cannot see a > property being removed while every line survives, and that is the failure that actually happens. **Where things live** — the reference that *owns* each concern (read it when that concern is in play): | Concern | Owner | |---|---| | The craft / the "why" (contrast · hierarchy · C.R.A.P. · layout safety) | `references/design-principles.md` |