deck-craft

# deck-craft Build projection-ready, content-dense, high-quality presentation decks from source material, through a disciplined pipeline: understand → unify the information spine → ready the environment & fonts → research-design round → build → render QA → per-page expert polish → de-AI-ify → speaker script → speaker notes. The output is a `.pptx` (plus a PDF for sharing, and an optional notes version) that reads cleanly when projected and tells one coherent story. This skill encodes a complete, reusable design system in `scripts/deck_kit.py` and the methodology in `references/`. Read this body for what to do and when; go to the referenced files for the detail. ## 1. When to use / not use This skill is oriented to **Chinese / mixed CJK-latin projection decks** (the divider chapter labels and the like are localizable to English; see §3 P-build and the `CHAPTER_LABEL` token in `deck_kit.py`). The dividing line is the **kind of work**, not just the trigger words: - **Light, single-`.pptx` read/write or mechanical generation** (parse a deck, pull its text, emit one slide from data, drop comments in, split/merge files): use the `pptx` skill. It is the right tool when no narrative design or per-page polish is needed. - **Research-driven narrative + per-page expert polish + projection typography + de-AI-ified report-grade deck** (turn a pile of research / interview / report material into one coherent, projection-facing story, then iterate it to high quality): use **this** skill. That is the report-grade case the whole pipeline below exists for. - If you have a more general-purpose slide pipeline available, reach for this skill specifically when the deck must be content-dense, projection-readable (16 pt body floor), and free of AI tone. **Not for:** a single one-off diagram, a plain data-table export, or a one- or two-spot tweak to an existing deck. ## 2. Core principles (three invariants) 1. **Projection floor: body >= 16 pt; quiet luxury.** A 13.333 in canvas on a 2–4 m screen viewed from 3–8 m has a far smaller visual angle than a web page at arm's length, so any text carrying real information stays >= 16 pt. The look is white / near-white foundation (~90%) + a neutral grey scale + ONE desaturated accent used only as garnish (<5% area), with no full-page color blocks. 2. **findings-first.** Introduce the object objectively (what it is, what's there, what's good) BEFORE diagnosing it. "If you don't introduce it, how can you talk about its flaws?" The arc is introduce → diagnose → improve → close. 3. **Iterate only on the real render, never on an imagined one.** python-pptx is invisible; CJK fallback, overflow, and line-breaks only show up rendered. Render after every layout-affecting change and look before judging. ## 3. The nine-step pipeline (P0–P9) **Match the ceremony to the task size.** A 5–10 page small deck trims P3 and P6: build directly with `deck_kit.py` and do one self-review round; the "lead self-builds and self-verifies" lines below are about who owns quality, not a ban on a quick path. Only a content-dense large report walks the full parallel-expert flow. Default for a real report is the whole pipeline; full detail and the WHY of each step is in `references/pipeline.md`. - **P0 · Understand the domain** (lead agent, not outsourced): read the course / brand / business material, align on audience and taste, output a short alignment note. Building context yourself is what lets you judge and synthesize. - **P1 · Absorb sources + lock the information spine** (lead): convert all sources to md, read each, find framework conflicts, and lock ONE backbone (others map under it). A deck's quality is first its information architecture. See `references/content_and_narrative.md`. - **P2 · Environment & fonts ready** (lead): verify python-pptx / Pillow / render chain; install premium fonts and **render-test Regular + Bold before a full build**. Run `scripts/install_fonts.sh`; see `references/build_and_qa.md` §7. No network? `install_fonts.sh` now skips the download and you fall back to an installed system CJK font (macOS PingFang SC, or an already-installed 思源 / Source Han); point `deck_kit.py`'s SANS/SERIF at it and render-verify. - **P3 · Research-design round**: write a per-round planning doc, then launch three parallel experts in ONE message (design-system [load practical-ui if present] ‖ content & narrative [findings-first] ‖ image audit [verify every image]); each persists an md; then the **lead writes the synthesis doc itself** (per-page asset assignment + build increments). See `references/{design_system,content_and_narrative,image_audit}.md`. - **P4 · Build**: prefer the lead self-building the script with `scripts/deck_kit.py` (see `scripts/example_build.py` for the pattern, including `cards()` / `compare()` and the multi-chapter dispatch loop). The lead holding the script is what drives the per-page iteration. If you outsource, force the sub-agent to persist the script to a file and save incrementally (a build sub-agent once dropped its socket having saved nothing). - **P5 · Render QA**: `soffice → pdf → pdftoppm → PIL overview`; look at high-risk layouts first. Run `scripts/render_qa.py deck.pptx`. No LibreOffice? Open the `.pptx` in PowerPoint or Keynote and export a PDF (or per-slide thumbnails), then eyeball those instead. See `references/build_and_qa.md`. - **P6 · Per-page expert polish**: split pages into bands, launch several review experts in parallel (each loads practical-ui if present, uses the design system as yardstick, returns pixel-level findings); the **lead verifies findings itself**, rejecting false positives and taking only real ones, then fixes, re-renders, and runs a regression round. The gate to clear: **at least one parallel review round plus one regression round, with no open P0/P1.** - **P7 · De-AI-ify**: load humanizer-zh (op7418's public MIT skill; if it isn't installed, install it on demand with `npx skills add op7418/Humanizer-zh` and load it — if you truly can't, run `references/humanize.md`'s deck-specific checklist by hand); edit layout-coupled deck text yourself (re-render to watch length); change HOW it's said not WHAT (prove technical content unchanged with grep); **second self-check** so you don't swap one AI pattern for another. See `references/humanize.md`. - **P8 · Speaker script**: if the user hand-edited the deck, extract real per-page text from the LATEST file (the build script is now stale); write a spoken, `---`-paginated, emphasis-marked script; deliver the MD for confirmation BEFORE inserting. - **P9 · Insert speaker notes**: run `scripts/insert_notes.py` (drops headings + 〔...〕 cues, splits the body on blank lines into paragraphs, converts `**bold**`, asserts segment==slide count, writes a NEW file). ## 4. Sub-agent orchestration > This section assumes a Claude Code-style harness (parallel sub-agents; the Skill > tool). On any other agent runtime, read these as their semantic equivalents: > "sub-agents" → background or delegated sub-tasks, and "load a Skill via the Skill > tool" → load the corresponding capability. The method is unchanged; only the > mechanism's name is. - **Research round (P3):** three parallel experts in one message, all blocking (design ‖ content ‖ image audit). Write the per-round planning doc first so all three align on background, locked decisions, source paths, and output contract. - **Review rounds (P6):** several parallel review experts, each prompted to (1) if `practical-ui` is installed, load it via the Skill tool as the usability yardstick — it is a copyrighted-book adaptation this skill does not bundle, so when it is absent fall back to this skill's own quiet-luxury / contrast / hierarchy principles (`references/design_system.md`); (2) read the design system as the yardstick, (3) return page/location/severity findings. - **The lead must verify review findings itself.** Fix observed problems, not reported ones; reject unfounded reports (a "slide N font too small (P0)" that the render disproves) and take only real, actionable items. - **Heavy build:** prefer the lead self-holding context and self-building. If outsourced, require "persist the script to a file before continuing, save incrementally". Parallel = N Agent calls in ONE message, all blocking. One call per message = serial. Independent → parallel; dependent → serial. Full table in `references/pipeline.md`. ## 5. Quality gates (checklists) Full version with the "why" in `references/norms_and_lessons.md` §E. Quick form: **Before build:** [ ] lead read all sources itself · [ ] frameworks unified into one backbone · [ ] narrative is findings-first (setup chapter before diagnosis) · [ ] image-audit list done (figure ≠ file) · [ ] type scale locked (body >= 16 pt) · [ ] copy written plain (no AI tells) · [ ] premium fonts installed + render-verified (or system-font fallback chosen if no network) · [ ] content tied to course/audience theory · [ ] names only on the cover · [ ] heavy build self-built (or sub-agent persists early). **After build:** [ ] every layout change re-rendered and eyeballed (no LibreOffice → PowerPoint/Keynote PDF or thumbnails) · [ ] per-band parallel review experts (each loads practical-ui if present, else the built-in design system) · [ ] lead verified high-impact findings, rejected false positives · [ ] render chain macOS/zsh-safe · [ ] at least one review round plus one regression round, no open P0/P1. **Before delivery:** [ ] de-toning second self-check (no pattern swapped for another) · [ ] versioning `_vN.M`, archive old, new file for user-edited files · [ ] known boundaries/risks listed with a fallback (font fallback → PDF; no LibreOffice → PowerPoint/Keynote) · [ ] citations verified if any. ## 6. Norms quick-reference (the full list) These 13 norms are the deck-making domain knowledge; the full requirement / why / how for each is in `references/norms_and_lessons.md` §A. 1. **findings-first:** introduce before you critique. 2. **De-name:** member names only on the cover role cards; never per-page kickers. 3. **Chapter divider per chapter,** with a "chapter X of N" progress indicator. 4. **Body >= 16 pt:** projection floor; dense tables 14 pt is the only exception. 5. **Premium fonts:** Noto Serif SC (titles) + Noto Sans SC (body) + Inter (numbers); install and render-test both weights before a full build. 6. **Verify every image by eye:** figure number ≠ file number; contact sheet + full-res check; only verified images with corrected captions. 7. **Simplified cover:** white, restrained, accent as garnish. 8. **Minimal ending:** one centered serif line on white; references moved out. 9. **Design yardstick — practical-ui if present, else built-in:** if `practical-ui` is installed, load it as the usability yardstick; it is a copyrighted-book adaptation this skill does not bundle, so when absent, use this skill's own quiet-luxury color, accent <5%, no full-page color blocks (`design_system.md`). 10. **Per-page expert polish, not one-and-done:** render → parallel review → lead verifies → fix → re-render → regression; iterate to no open P0/P1. 11. **De-AI-ify with humanizer-zh:** op7418's public MIT skill — install it on demand if absent (`npx skills add op7418/Humanizer-zh`), else run `humanize.md`'s deck-specific checklist by hand; change how not what; prove technical content unchanged with grep; second self-check. 12. **Speaker script:** extract from the real .pptx; `---` per page; spoken, emphasis-marked; confirm the MD before inserting. 13. **Insert notes, spoken body only:** drop headings & 〔...〕; convert bold; segment==slide assertion; write a new file. This skill carries its own working discipline, self-contained (it needs no external rule files): understand before you act, audit before you execute, back up before irreversible rework, re-render on every visual change and judge only the real render, keep the palette desaturated (quiet luxury), make every iteration state its benefit, resolve multi-source conflicts by authority level, use four-zone directories with `_vN.M` versioning, and verify any citation before delivery. How each plays out in deck work is in `references/norms_and_lessons.md` §B. ## 7. Quick start A typical run: read the user's source material yourself, lock the spine, set the accent token, then drive the build from data. **Work in your own project, not the skill folder.** Copy `deck_kit.py` (and the `example_build.py` skeleton) into your project's working area and write your build script there. Leave the files under the skill directory untouched so the skill stays clean for the next deck. 1. `bash scripts/install_fonts.sh` (once), then render the example and confirm Regular vs Bold are distinct: `python3 scripts/example_build.py && python3 scripts/render_qa.py scripts/example_deck.pptx`. 2. Copy `deck_kit.py` into your project's working area, drop the `example_build.py` skeleton beside it, set `dk.set_accent("#XXXXXX")` and `dk.FOOTER_TEXT`, and replace the EXAMPLE content with your outline (see `assets/content_outline.schema.md`). 3. Build → `python3 render_qa.py your_deck.pptx` → read `/tmp/qa/overview.png` → fix → re-render. Iterate per §3 P6. 4. Speaker script → `python3 insert_notes.py --md script.md --src deck.pptx --out deck_with_notes.pptx`. **Scripts** (`scripts/`): `deck_kit.py` (the reusable design-system library, the heart), `example_build.py` (a worked example with cards/compare + a multi-chapter loop), `insert_notes.py`, `render_qa.py`, `contact_sheet.py`, `install_fonts.sh`. **References** (`references/`): `pipeline.md`, `design_system.md`, `build_and_qa.md`, `image_audit.md`, `content_and_narrative.md`, `humanize.md`, `norms_and_lessons.md`. **Versioning:** non-destructive. New versions go as `_vN.M` to the deliverables zone, superseded versions to the archive zone, and a user-edited file is always copied to a new file, never overwritten.