deck-architect

Files (20)

• SKILL.md
• deck-architect.skill
• example.md · references/
• failure-modes.md · references/
• forbidden-phrases.md · references/
• html-renderer-reference.html · references/
• html-renderer.md · references/
• pressure-test.md · references/
• rationalizations.md · references/
• slide-craft.md · references/
• visual-specs.md · references/
• visuals.md · references/
• lint-deck.js · scripts/
• render-visual.js · scripts/
• bar.js · scripts/visuals/
• flow.js · scripts/visuals/
• graph.js · scripts/visuals/
• quadrant.js · scripts/visuals/
• tokens.js · scripts/visuals/
• waterfall.js · scripts/visuals/

SKILL.md (first lines)

# Deck Architect

Handles the part of deck-building AI is bad at: **content and structure**. Not visuals. Produces a sharp outline; hands off to a visual-design skill (e.g. `pptx`) for rendering.

## When NOT to use

- User only wants visual polish on already-finalized slides → use `pptx` directly
- Single-slide updates / one-off charts → overhead exceeds value
- The deliverable is a written doc, not a deck → use a writing skill
- The deck must follow a locked corporate template that conflicts with full-sentence titles or main-flow rollback slides — the skill's prescriptions will fight the template; flag this and let the user choose
- User wants speaker notes only for an existing deck — the skill produces full outlines, not note-only revisions
- Someone else owns the structural decisions and the user is just executing — the skill pushes back on structure; that's friction in this case
- Non-English decks where the user wants enforcement on style — the structural checks (no agenda, full-sentence titles, tradeoff, rollback) still apply, but the slop-phrase list is English-only

## The Iron Law

**No slides without Audience + Takeaway + Spine first.**

Applies to new decks AND edits. If you catch yourself drafting before those three are locked, stop and go back to Phase 0. The rationalizations table in [references/rationalizations.md](references/rationalizations.md) covers every excuse you'll be tempted by — read it once, then don't re-litigate.

## The AI Slop Test

Before finalizing, ask: **"If someone said 'Claude wrote this deck,' would it be obvious?"**

A deck that passes:
- Slide titles are full-sentence messages, specific to this project
- Every substantive slide has at least one concrete detail (a name, number, date, artifact)
- The deck argues something — it doesn't just "cover" a topic
- Nothing could be copy-pasted to another company with nouns swapped

**When the test fails OR you're uncertain: Read `references/forbidden-phrases.md`** for the full list and structural tells. Use the TL;DR below as a first pass; load the reference when (a) a slide title or body hits one of the listed phrases, (b) you're writing fresh persuasive copy where slop risk is high (pitch, exec recommendation, board update), or (c) the audience is sophisticated enough to penalize any generic language. If the TL;DR catches everything, no need to load.

> **TL;DR if you don't load the reference:** ban hedged corporate filler — "leverage," "unlock," "drive alignment," "robust," "seamlessly," "stakeholders," "ecosystem," "significant impact," "in today's fast-paced world," "we are excited to." Replace each with a concrete noun or verb that carries information. "Significant impact on retention" → "D30 retention moved from 22% to 41%." Specificity is what kills the slop.

## Operating principles

- **Audience first, always.** Phase 0 is non-negotiable. The audience determines the takeaway, the spine, the wins to surface, and the main-vs-backup split.
- **Audience is the hero, not the presenter.** Frame as their problem → their transformation. The presenter is the mentor.
- **Strategy first, slides last.** No slide content until audience, brief, takeaway, and spine are locked.
- **Pull for specifics, resist topics.** Topics produce generic output; specifics produce a deck only this user could give.
- **Honesty is a persuasion tool.** Name the tradeoff before the audience does.
- **Adversarial read before the live read.** Pressure-test before presenting (Phase 6).
- **Contrast creates attention.** Alternate problem/solution, current/future. Monotone = forgotten.
- **Progressive disclosure by default.** Main flow + backup layer.
- **Credit humans specifically.** Names + specific wins, never anonymous "we."
- **Protect opening and close.** Primacy + recency. Don't waste either on agenda or thanks.
- **Text-first on visuals.** Default text-only. Earn each visual.

---

## Workflow

Follow phases in order. Don't skip ahead.

If the user brings an existing draft, don't start from scratch — but don't skip Phase 0 either. Run Phases 0–1 (infer answers from the draft, confirm with user), then use Phase 4 as the main working mode. All other phases still run — driven by the existing draft rather than a blank page. Phase 2 (spine) re-validates or replaces the existing structure; Phase 3 becomes a slot-by-slot revision (cut / merge / rewrite titles / add missing hook or STAR); Phases 5–8 unchanged. Output a revised outline plus a "what changed and why" section (the Phase 8 output schema has a slot for this).

### Phase 0 — Model the audience

**Lock this before anything else.** Ask these five questions in one compact block:

1. **Who's in the room — specifically?** Names or roles. Hardest sell? Decision-maker? Likely interrupters?
2. **What do they care about?** Their incentives, not the topic. ROI/risk (CFO), strategic fit (CEO), technical rigor (eng leaders), career impact (often the real one).
3. **What do they already know/believe?** Skip what they know. Anticipate what they'll disagree with.
4. **What's the transformation?** Walk-in state → walk-out state. ("Skeptical of budget" → "convinced this is the cheapest insurance we can buy.")
5. **What objections / deep-dive questions will they raise?** List 3–5. These feed the backup layer (Phase 8).

Output: an **Audience Model block** at the top of your response. Cite it whenever you cut a slide in Phase 4.

**If the user won't answer after one push:** infer from context and mark each inferred answer with `[INFERRED — confirm]` so they can correct in one pass. Better an inferred Audience Model than no Audience Model.

**If the user brought an existing draft:** infer answers from it before asking. Audience clues = formality, jargon density, named stakeholders. Takeaway clues = the close (or its absence). Objection clues = the slides that already exist defensively (TCO, rollback, comparison tables). Confirm inferences with the user, don't replace asking.

For a real example of a complete Audience Model block, see [references/example.md](references/example.md).

### Phase 1 — The rest of the brief

One block, four items:

1. **Decision or action.** What do you want them to do/decide/approve/remember? If there isn't one, flag it — the deck has no purpose.
2. **Format & time.** Live presentation, async pre-read, or both? Minutes? Live decks and slide docs aren't interchangeable.
3. **Constraints.** Slide-count cap? Required sections? Brand/template?
4. **One-sentence takeaway.** If they remember one sentence, what is it? Shaped by Phase 0 — same project, different audiences, different takeaways. Don't move on without this.

Same fallback as Phase 0: if the user won't answer after one push, infer and mark with `[INFERRED — confirm]`. Exception: the one-sentence takeaway. Don't infer this — help the user articulate it instead. A wrong takeaway is worse than a missing one.

**Existing-draft mode exception:** if there's no live dialogue (user handed you a draft and expects a revised outline back), templatize the takeaway as `[USER: write the one-sentence takeaway]` and flag it as a blocking item in the handoff notes. Do not invent one.

**Phase 1a — Team credit (conditional).** If the deck describes work by multiple people (any "we," "the team," named collaborators, cross-functional shipping of something non-trivial), ask once: *"Is this a team effort? If so, tell me who contributed to which key wins so credit lands with the right people."* Then:

- **Tie specific wins to specific humans on the slide.** Not "the team reduced latency" — "Priya rewrote the caching layer, cutting p99 latency 42%."
- **Surface individual wins in speaker notes** even when the slide stays clean — verbal credit lands harder than on-slide text.
- **Add a Credits slide near the end** (second-to-last, before the takeaway close) when the contributor list is meaningful. Specific, name-by-name. "Thanks to the team" gets cut.
- **Never invent attributions.** If unsure, ask or use neutral framing.

**Phase 1b — Existing assets (conditional).** If the user mentions specific assets/screenshots/imagery, ask once where to find them and what else is available. Don't ask by default — friction without payoff.

### Phase 2 — Pick the narrative spine

Choose ONE structure. State which and why before outlining.

| Situation | Spine |
|---|---|
| Executive / business / recommendation | **SCQA + Pyramid (Minto)** — Situation, Complication, Question, Answer-up-front, then 2–4 MECE supporting arguments |
| Technical talk / conference | **Hook → Problem → Insight → Evidence → Takeaway** — single technical claim, not a survey |
| Pitch (funding/sales/partnership) | **Problem → Why Now → Solution → Why Us → Proof → Ask** |
| Update / status | **Headline → What changed → What it means → What's next** — headline first, details on tap |

If the situation doesn't fit cleanly, pick the closest and state the adaptation.

**Spine details:**
- **SCQA:** answer-up-front (the recommendation is slide 1 of body), then 2–4 supporting arguments. Arguments must be **MECE** — no overlap, full coverage. Two arguments saying the same thing? Collapse them.
- **Hook→Insight→Evidence:** time budget ~15% hook/intro, 60–70% body, 15–20% demo + close. The insight is a *single* technical claim, not a survey.
- **Pitch:** use only when explicitly pitching for funding, sale, or partnership.
- **Update:** resist walking through every workstream. Headline first; details on tap.

### Phase 3 — Draft the slide list (in text)

Numbered list. Each slide:

From dlomibao/dl_skills, MIT.

More from dlomibao/dl_skills