gaik-project/gaik-toolkit/brief-to-slides

Brief to Slides

Builds a highly visual, editable .pptx (optionally also a Claude Slides deck) with speaker-ready notes on every slide, exact timing, citations and a verified layout. It works from a three-field request and fills everything else from a default brief distilled from a complete teaching deck (assets/template.pptx).

1. Inputs

Required (ask one short question only if one is missing):

1. Topic or title
2. Audience (who, prior knowledge)
3. Length: minutes or number of slides

Optional (apply the default and state it in one line of the reply):

1a. Source mode (decide before planning)

• Strict: use only the user's data and sources (including links they gave). No web search.

Claims not supported by them are left out or marked as gaps.

• Extended: the user's material comes first; online research fills gaps, adds evidence and

checks that facts are current.

Decide it this way:

1. Always ask first whether the user has their own data, files or source links (Q1), unless

the request already includes them. If yes, ask them to attach files (PDF, Word, PowerPoint, Excel, CSV, text/Markdown, JSON, HTML, images) and paste links separated by commas or one per line; collect them with scripts/collect_sources.py.

1. Material provided → the next question is the mode (Q2): "Only my material (strict)" /

"My material + online sources (extended)". The user named a mode already → use it.

1. No material → extended; say so in one line.
2. Nobody can answer (unattended run): strict if material was attached, otherwise extended;

say so at the top of the reply.

A template file, logo or outline alone is not source material. Rules per mode: references/research-and-citations.md.

1b. Intake questions (before research or building)

Ask at most 10 questions with AskUserQuestion, in this order, skipping anything the request or attachments already answer. Exact wording, options, previews and answer mapping: references/intake-questions.md.

1. Own material (Q1, always first) → if yes, upload step (files + links), then

search mode (Q2: strict / extended).

1. Content and title slide: opening question, activities, presenter name/affiliation,

heading style (title only vs section label + title).

1. Footer, logo, design: running footer and slide numbers, logo yes/no, design/template and

output format; then logo position (top right, top left, bottom right, bottom left) if needed.

If the user declines, skips or nobody can answer: no opening question, no activities, no presenter details, title only, slide numbers only, no logo, default design. State these choices in the reply.

A detailed user brief always overrides these defaults. Read references/default-brief.md first: it is the full brief applied when the user gives only the three required inputs.

2. Workflow (keep a task list)

1. Brief. Ask the intake questions (§1b). Turn the request and answers into a brief:

required inputs + answers + chosen defaults. Compute the slide count (≈3 min per teaching slide, 2 per talk slide, 5–30 slides) and per-slide minutes that sum exactly to the length. References slides are extra and untimed.

1. Environment. bash scripts/setup_env.sh (fonts, icons, libraries, render tools).
2. Template.

• None given: use assets/blank-template.pptx with the default THEME.
• Given: copy it; run python scripts/inspect_template.py T.pptx --render tmpl_preview;

look at the contact sheet; write a THEME override (layout name, colours, kicker/title/ source/page-number boxes, title background, logos the user supplied; fonts lists the families for the Slides deck). THEME styles only those recurring parts: the helpers (card, banner, chip, table, …) take the palette in dsl.py as default arguments, so map the palette roles in references/design-system.md to the template's colours in your spec and pass them as color=/fill=. Install missing fonts.

1. Sources. Read all provided material first (every file in sources.json, every link;

report any that fail) and keep a source ledger (claim → source → page/section/URL). Strict: no web search; list gaps. Extended: research online (official sources first) for gaps and anything time-sensitive; note check dates; flag conflicts with the user's material instead of overriding it (references/research-and-citations.md).

1. Plan. One idea per slide; pick a pattern per slide from references/slide-patterns.md

(vary them); thread the running example; write the 4–5 key phrases per slide. Title slide = cover() only (title, subtitle, optional series label; question/presenter only if given). Put the intake answers for heading style, footer, slide numbers and logo into THEME (show_kicker, footer_text, page_numbers, logo); the renderers place them.

1. Write the spec. Copy scripts/example_spec.py; fill SLIDES (id, kind, kicker, title,

els, minutes, notes, source), TITLE, SECTIONS, THEME. Use the DSL and helpers in scripts/dsl.py; size every text box with text_h(). Write notes per references/speaker-notes.md (activities need instructions, timing, sample answer, debrief). Start each timed slide's notes with its minutes, e.g. [3 min]: check_deck.py adds up those prefixes, and build.py warns when one differs from the slide's minutes.

1. Build. python scripts/build.py spec.py --template T --out deck.pptx --preview preview.html
2. Check. `python scripts/check_deck.py --pptx deck.pptx --minutes N --preview preview.html

--forbid "<old template text>" must print OK. Then bash scripts/render_preview.sh deck.pptx out 72 and inspect out/sheet.png` and each slide. Fix clipping, overlaps, cramped or empty areas, one-line labels that wrap; rebuild until clean (references/build-notes.md).

1. Slides deck (optional). references/slides-artifact.md.
2. Deliver. Send the .pptx. Reply in a few lines: slide count and timing, defaults you

assumed, the source mode, gaps (strict) or added sources and conflicts (extended), facts verified (with date), and template elements not reproduced exactly (font substitutes, simplified drawings instead of screenshots, masters not carried into a Slides deck). Mention that example cases are invented.

1. Ask for changes. End the delivery by asking whether the user wants any changes

(AskUserQuestion: "No, it's ready" / "Yes, I'll describe them"; not one of the 10 intake questions). If they describe changes, make targeted changes only: edit just the affected slides (or THEME for deck-wide items), keep every other slide as it was, keep notes, timing total and citations consistent, rebuild, run check_deck.py, look at the changed slides, run scripts/diff_decks.py old.pptx new.pptx to confirm nothing else changed, deliver as _v2 with a slide N: what changed list, and ask again. If the user edited the .pptx themselves, change their file directly instead of rebuilding (references/revisions.md).

3. Non-negotiables

• Notes in the Notes pane of every slide; timings sum exactly; no leftover template slides,

text, notes or hidden slides.

• A meaningful visual on nearly every teaching slide; 4–5 self-contained phrases; never shrink

text below 12 pt or to fit: simplify and move detail to notes.

• No invented sources, statistics, quotes, availability or screenshots; sourced claims cited on

the slide and in references.

• No label words on slides ("illustrative", "mock-up", "fictional", "synthetic data"): invented

examples and simplified interface drawings are disclosed in the speaker notes and the reply.

• Title slide carries nothing beyond cover(): no illustrations, mock-ups, cards or icons.
• No activities, opening question or presenter details unless the user provided or approved them.
• Strict mode: every factual claim on slides and in notes traces to the user's material.
• No logos or brand marks unless the user supplies them. No section label above titles unless the

user chose it. No generic robot imagery.

Files

• references/default-brief.md: full default brief (deliverable, arc, design, notes, research, verification)
• references/design-system.md: default theme: palette roles, type scale, chrome, motifs
• references/slide-patterns.md: 20 patterns from the template deck, when to use, helpers
• references/intake-questions.md: the ≤10 intake questions, upload step, options, defaults, mapping
• references/research-and-citations.md: strict/extended source modes, ledger, citations
• references/revisions.md: asking for changes after delivery and making targeted edits
• references/speaker-notes.md, references/build-notes.md, references/slides-artifact.md
• assets/template.pptx: complete 22-slide example deck (60-min session) showing every pattern with notes
• assets/blank-template.pptx: same design, no slides: the default starting file
• scripts/: setup_env.sh, collect_sources.py, inspect_template.py, dsl.py, render_pptx.py, render_html.py, build.py, check_deck.py, diff_decks.py, render_preview.sh, example_spec.py