Technical Deck Builder
You are responsible for turning a structured insight_brief.json storyboard into a crisp, zero-overflow 16:9 technical presentation (.pptx) using render_pptx.py.
By default, render_pptx.py reads workspace/insight_brief.json, resolves figures/ relative to workspace/, and writes workspace/output_deck.pptx. In any project with a different layout, pass --input, --output, and --workspace explicitly.
Slide Narrative & Visual Density Rules
Before rendering, verify insight_brief.json satisfies every density and layout constraint:
- Slide Count: 7 to 12 slides total (
slidesarray). - Word Budget:
- Every bullet in
bulletsand every point inleft_column.points/right_column.pointsMUST be <= 12 words (prefer <= 10 words on visual slides). - Every
key_takeawayMUST be <= 24 words (one sharp sentence). - Every
steps[i].detailinmechanismslides MUST be <= 18 words (prefer <= 14 words).
- Every bullet in
- Bullet Density & Visual Balance: Max 5 bullets per slide or column (prefer 3–4 bullets when paired with a visual). Never dump paragraphs into slides—move detailed prose to
speaker_notes. - Layout-Specific Requirements:
title: Slide 1, sets the core thesis inkey_takeaway; optionally acceptsfigure_pathfor a right-side hero illustration.task_domain: Explains the problem domain and concrete example; pairs concise bullets with an optionalfigure_pathillustration.overview: Summarizes problem, current solution, proposed solution, contributions, and result; pairs with an optionalfigure_pathorleft_column/right_column.comparison: Requiresleft_column("Prior Bottleneck") andright_column("New Insight"); optionally acceptsfigure_pathto pair stacked contrast cards with a visual diagram.mechanism: Requiressteps(2–4 causal steps) translating math into engineering intuition; optionally acceptsfigure_pathfor a side-by-side mechanism diagram.figure_takeaway: Requiresfigure_pathpointing to an existing PNG, JPG, or SVG (resolved relative to--workspace) and a concisefigure_caption.results: Highlights benchmark gains and qualitative demos; optionally acceptsfigure_pathfor a demo/chart visual.evidence: Highlights ablation deltas proving causality; optionally acceptsfigure_pathfor an ablation chart or plot.tradeoffs: Highlights assumptions, compute/memory costs, and failure modes; optionally acceptsfigure_pathfor a scaling or failure-mode illustration.
- Assertion Titles, Native Editable Shapes/Tables, and 70–80% Visual Scale (
render_pptx.py):- Assertion Titles (No Redundant Takeaway Banner):
add_chromerendersspec.titleas a23ptbold assertion headline (max 2 lines) without a separateKey Takeaway:banner, freeing0.69"of vertical height. - Balanced Slide 1 (
highlights): Slide 1 supports a 3-card Executive Highlight Grid (Core Mechanism,Headline Result,Scope) with15ptbody text filling the lower 50% of the cover slide. - Projection Font Floor (
>= 14ptNative Text): Results Headline Pill (Slide 7) uses16pt–18ptbold; Pipeline Step Sub-captions (Slide 4) use14ptminimum; Title Slide summary card body text uses15ptminimum (only Slide 2's11ptnotation footnote and slide footer may be smaller). - Full-Height Dual-Panel Slot (
5.42"): Dual-panel visual slides (figure_paths) ban bottom 3-card/bullet strips and expand visuals to5.42"height (~85%of content height), paired with600 × 520SVGs so zero dead band appears above the footer. Slide 2'snotation_primersits aty = 6.95". - Native Editable Tables, Flows, Column Matrices & Box Diagrams (
panels): Usenative_table,native_flow,native_columns, andpanels(type: "diagram") so comparison tables, linear process flows, Limitation/Future-Direction matrices, and all box-and-arrow schematics (flowcharts, nested containers, before/after state boxes) render as razor-sharp, editablepython-pptxgrouped shapes (MSO_SHAPE.ROUNDED_RECTANGLE, native text runs with subscripts,MSO_CONNECTOR.STRAIGHTarrows, grouped viaadd_group_shape()) using the exact Soft Pastel Editorial palette and1.5ptrounded borders. Reserve SVGs (type: "image") strictly for quantitative data visualizations. - Full-Bleed Borderless Charts & Tight Margins (
0.35"):add_figure_box(..., framed=False)places SVG visuals directly on the#FAF9F6slide canvas without padded outer card boxes, using tight0.35"left/right margins (w=12.63") to maximize chart area. - Full-Width Results Layout (
results): Never squeeze a multi-group results chart beside a giant side card. Renderhero_metricas a compact top-right corner badge and let the results chart span 100% of the content width (12.63"). - Optional Bottom Strip (
bullets: []) & Slide 2 Footnote: Bottom bullet strips default to empty so visuals expand to5.36"height (~80% of slide). Slide 2'snotation_primerrenders as a single-line11ptmuted footnote pinned aty = 7.10". - Compact Native Pipeline Cards (
native_flow): Linear 4-step pipeline cards stay compact (~55%slide height) with a 1-line plain-English definition or core equation (caption) at the bottom of each card. - Modular Grids (
figure_paths): Whenfigure_pathsis provided (2–4 modular SVGs),render_pptx.pyrenders each panel in its own independent PPTX shape card inside the visual zone. - Slide 2
notation_primer,resultshero_metric, Causal→Connectors & Final Slideclosing_takeaway:render_pptx.pyrendersnotation_primeras a Key Notation & Metric Strip on Slide 2,hero_metricas a36ptHero Metric Callout Card alongside the Results chart (5.20"height),→causal connectors between consecutivemechanismstep cards, andclosing_takeawayas a high-contrast Paradigm-Shift Closing Banner on the final slide. - Universal
<sub>/<sup>Math, Non-Breaking Deltas & Light-Mode Transparency:render_pptx.pyrenders<sub>/<sup>andX_sub/X^supvariables using native OOXML baseline subscripts/superscripts, normalizes(-41.3)to non-breaking(−41.3)and~84%to≈84%, and converts pure-white PDF figure backgrounds (RGB > 245) to transparent (alpha = 0).
- Assertion Titles (No Redundant Takeaway Banner):
Execution Workflow
Prerequisites
Ensure python-pptx and pydantic are installed in the active Python environment (e.g., pip install -r ./requirements.txt inside the skill folder if missing).
Step 1: Validate insight_brief.json
Run the deterministic Pydantic validator first (adjusting --input / --workspace if not using workspace/):
python3 <skill-dir>/scripts/render_pptx.py --validate-only \
--input <path/to/insight_brief.json> \
--workspace <path/to/assets_dir>
If validation fails:
- Read the exact field and word-count error reported by Pydantic.
- Edit
insight_brief.jsonto tighten verbose bullets (<= 12 words), fix missing layout fields, or correctfigure_pathreferences. - Re-run
--validate-onlyuntil it exits with code0.
Step 2: Render the .pptx Deck
Once validation passes, run the renderer:
python3 <skill-dir>/scripts/render_pptx.py \
--input <path/to/insight_brief.json> \
--output <path/to/output_deck.pptx> \
--workspace <path/to/assets_dir>
(When working in a project that uses the standard workspace/ directory, you can omit --input, --output, and --workspace.)
Step 3: Automated Visual QA (deck-reviewer) & Verify Output
After rendering output_deck.pptx, invoke the deck-reviewer skill (.agent/skills/deck-reviewer/SKILL.md):
- Rasterize all slides to PNGs via
.agent/skills/deck-reviewer/scripts/rasterize_deck.py. - Inspect every slide against the 5-point visual QA checklist (no text/curve overlaps, no stretched aspect ratios, no clipping or >3-line card wrapping, consistent dark-mode theme, consistent Unicode math).
- If any slide fails, patch the offending SVG,
insight_brief.jsoncopy, or layout, re-render, and re-verify (up to 2 QA iterations) before reporting the final slide count and output path.