Deck Builder

Deck Builder

Use this skill to turn messy material into a reviewable deck.md, get the human to approve it, and then produce slides from that approved brief.

Core Contract

deck.md is the planning artifact and source of truth. Do not invent a parallel schema.

Hard rules:

• Draft or normalize a complete deck.md first.
• Keep status: draft until the human approves production.
• Do not build slides, generate images, assemble PDFs, or export PPTX files before approval.
• Always include a first slide with type: cover; it introduces the deck and does not replace the executive summary.
• Default production_defaults.default_slide_mode to designer-mode unless the user asks for ppt-shapes or mixed/editable output.
• Declare every model input in designer_assets before approval; do not send or use undeclared files.
• Treat all logos, templates, old decks, screenshots, brand guides, icon packs, fonts, and reference images as external assets supplied by the user or declared by URL/path. This public skill has no bundled visual asset library.
• If the request includes data, CSV/Excel, SQL, metrics, benchmarks, or asks for analysis/rationale, complete the data-analysis workflow before drafting deck.md.
• Make the takeaway unmistakable on every slide. Use charts as proof, not decoration or a catalog of analysis cuts.
• For pure designer-mode, deliver PDF output only; add OCR/searchable text when available and report if OCR was not applied.
• Use the standard footer unless the approved brief disables it: small CR lower-left and simple page numbers (1, 2, 3) lower-right.
• Render and inspect the produced artifact before delivery; repair and rerender failed slides.
• For post-render changes, create a review deck.md version and regenerate only changed slides.
• Save meaningful specs and production rounds under the standard instance structure.

Fast Workflow

1. Classify the request: outline, content plan, data-to-deck, critique, designer-mode PDF, editable PPTX, or mixed deck.
2. If data or SQL is involved, preserve inputs, create analysis/chart CSVs, write notes and a manifest, then reference them in deck.md.
3. Draft or update deck.md with the narrative, action titles, slide types, production defaults, declared assets, and analysis artifacts when relevant.
4. Send the full draft deck.md to the human for approval.
5. After approval, validate the brief, prepare declared assets, validate data refs, and produce only in the approved mode.
6. Render, inspect, repair, and save the output in a production instance.
7. For review changes, fork from the previous approved brief, add ## Revision Brief, and reuse unchanged slides.

If the build is simple, keep the workflow simple. Do not create extra planning files unless they materially help review or production.

Reference Router

Read only the files needed for the task:

• references/SPEC.md - authoritative deck.md schema, defaults, precedence, and output rules.
• references/deck.md - quick-start starter brief.
• references/deck.full.md - rich starter with assets, revision brief, design tokens, and advanced designer-mode controls.
• references/standards/deck-validation.md - hard validation rules and self-check checklist.
• references/standards/data-analysis-workflow.md - SQL/CSV/spreadsheet analysis preflight, artifact layout, manifest schema, and chart economy rules.
• references/standards/slide-archetypes.md - valid slide type values and preferred production modes.
• references/standards/narrative-templates.md - SCR, pyramid, problem-solution, and update templates.
• references/standards/artifact-structure.md - specs, assets, instances, image folders, method files, manifests, and outputs.
• references/standards/image-prompts.md - designer-mode prompt rules and image-generation defaults.
• references/deck-workflow.md - deck-level storyline and consulting narrative rules.
• references/consulting-slide-standards.md - action-title, proof, source, and pre-flight standards
• references/standards/slide-design-principles.md - visual execution: canvas, margins, layout zones, typography hierarchy, whitespace, chart design, color discipline, alignment, and pre-design checklist.
• references/single-slide-workflow.md - one-slide build or critique sequence.
• references/designer-mode-workflow.md - designer-mode production and review loop.
• references/designer-mode-gpt-image-prompt-scaffold.md - convert an approved slide block into a gpt-image-2 prompt.
• references/designer-mode-direct-api-pattern.md - direct OpenAI Image API fallback, only after Codex path failure and human approval.
• references/pptx-production.md - editable PPTX production with artifact-tool.

Production Modes

Use designer-mode for premium visual slides and image-backed explanatory pages. Generate slide by slide with gpt-image-2 through Codex OAuth/Codex image tooling first. Use direct API-key generation only after that path fails and the human approves the fallback.

Use ppt-shapes for editable analytical slides, precise charts, tables, process flows, matrices, and decks where the user needs a PowerPoint-native file. Prefer:

bashCopy code
python scripts/build_pptx_artifact_tool.py OUTPUT.pptx APPROVED_DECK.md

This is the public editable-PPTX path. It creates an isolated artifact-tool workspace with src/, scratch/, and output/; uses editable presentation primitives; exports PPTX, PNG previews, layout JSON, and a quality report; and prepares only assets declared in the approved brief.

Use mixed only when specific slides need different modes. Set mode: explicitly per slide.

External Asset Contract

The installable skill is intentionally asset-neutral. Do not assume any bundled templates, logo sets, icon packs, deck examples, fonts, or brand materials exist inside the skill.

When the user provides assets, add them to designer_assets before approval. Supported generic types include logo, ppt-template, existing-deck, slide-preview, brand-guide, reference-image, screenshot, icon-pack, font, and other.

For designer-mode, prepare declared non-image assets into model-readable inputs and record them in method/model-inputs.yaml.

For ppt-shapes, pass declared local assets through the artifact-tool workspace under scratch/assets/ and record them in scratch/external-assets.json. Use them only when referenced by scope: deck or slide-level asset_refs.

If an approved deck marks an asset as required: true and it cannot be found or prepared, stop and report the missing asset. Optional missing assets should not block storyline planning or validation.

Validation Before Delivery

Before delivering, check:

• the current deck.md is approved
• data-driven decks have analysis_artifacts, local chart CSVs, notes/manifest, and clear caveats
• narrative template and slide types are valid
• the first slide is type: cover
• non-cover slide titles are action titles and the title sequence tells the argument
• each slide has one consulting takeaway and any chart directly proves it
• quantitative claims have sources
• all asset_refs resolve to declared designer_assets
• prepared model inputs are recorded in method/model-inputs.yaml when designer assets are used
• output has been rendered and inspected for text accuracy, overlap, clipping, logo placement, safe margins, and footer
• production artifacts are stored in the instance structure
• review changes use a new review spec and regenerate only changed slides

Full validation lives in references/standards/deck-validation.md.