winter-super-cli 2026.5.15

package/resources/local/codex/plugins/cache/openai-primary-runtime/presentations/26.505.10851/skills/presentations/SKILL.md

@@ -0,0 +1,743 @@
+---
+name: Presentations
+description: Build premium editorial analytics PPTX decks with artifact-tool presentation JSX, using ruthless narrative editing, chart-first storytelling, rendered critique, and iteration until the output beats the reference deck.
+---
+
+# Presentations
+
+`Presentations` is for serious, high-polish presentation work where "clean" is
+not enough. The target is an editable PowerPoint deck that feels like a strong
+editor, a strong analyst, and a strong designer built it together.
+
+Use this skill for analytics narratives, investor/operating reviews, strategy
+stories, product/business performance decks, and any PPTX task where the user
+asks to beat a reference deck.
+
+## Operating Contract
+
+Use artifact-tool presentation JSX only. The bundled Codex runtime provides
+`@oai/artifact-tool` version 2.7.3 or newer and exposes
+`@oai/artifact-tool/presentation-jsx`.
+
+Do not require or import a separate presentation runtime package. PPTX
+export/render behavior must be accessed through artifact-tool.
+
+For generated raster images or reference comps, use the Codex imagegen tool.
+Bundled scripts may write imagegen prompt files, but must not call external
+image APIs or read API keys.
+
+Thread-scoped paths:
+
+- `SKILL_DIR=<absolute path to the installed Presentations skill>`
+- `THREAD_ID=${CODEX_THREAD_ID:-manual-<timestamp-or-short-random-suffix>}`
+- `WORKSPACE=$PWD/outputs/$THREAD_ID/presentations/<task-slug>`
+- `SLIDES_DIR=$WORKSPACE/slides`
+- `PREVIEW_DIR=$WORKSPACE/preview`
+- `LAYOUT_DIR=$WORKSPACE/layout`
+- `ASSET_DIR=$WORKSPACE/assets`
+- `QA_DIR=$WORKSPACE/qa`
+- `OUTPUT_DIR=<user-provided output dir if any, otherwise $WORKSPACE/output>`
+- `FINAL_PPTX=$OUTPUT_DIR/<relevant-deck-title-slug>.pptx`
+
+Use absolute paths in commands and handoffs. Keep all generated planning text
+notes, preview PNGs, contact sheets, layout JSON, imagegen prompt files,
+temporary reference images, and other scratch files inside this thread-scoped
+`$WORKSPACE`. Keep only final deliverables in `$OUTPUT_DIR`. If the user
+provides an external output directory, write or copy only final deliverables
+there; generated `.txt` plans, contact sheets, previews, layout files, prompt
+files, and generated scripts must still stay under `$WORKSPACE`.
+Name the final PPTX with a short, relevant title derived from the deck topic or
+requested deliverable. Do not use generic filenames such as `output.pptx`,
+`deck.pptx`, or `deck.final.pptx`.
+
+Never use OS temp folders, a shared scratch folder such as
+`.presentation_workspaces`, `presentation-workspaces`,
+`presentation_workspaces`, `out`, or a bare repo-local deck slug unless the path
+is under `outputs/$THREAD_ID/presentations/`. If `CODEX_THREAD_ID` is
+unavailable, generate a manual id with timestamp plus a short random suffix.
+
+## North Star
+
+The deck must win the contact-sheet test. At thumbnail size, it should show a
+coherent visual system, distinct slide rhythms, and evidence-led storytelling.
+At readable size, every slide should have a claim, a proof object, and no filler.
+
+This skill rejects "serviceable" output. A deck can pass layout checks and still
+fail. If it looks like a generic SaaS dashboard, consulting card grid, or
+autogenerated template after replacing the company name, keep iterating.
+
+## Mandatory Workflow
+
+1. Confirm the task mode.
+2. Extract the source story.
+3. Write the claim spine.
+4. Lock the design system.
+5. Plan the contact sheet.
+6. Build editable artifact-tool presentation JSX slides.
+7. Render previews and layout JSON.
+8. Score against the comeback rubric.
+9. Iterate the weakest slides.
+10. Export the final PPTX only after the rendered deck beats the target or the
+    remaining gap is explicitly documented.
+11. Clean up generated planning text notes, QA scratch files, contact sheets,
+    preview images, generated slide modules/scripts, layout JSON, manifests,
+    prompt text files, and other temporary images before the final response.
+
+### Task Modes
+
+- `reference-beating`: user supplied or named a deck to beat. This is the
+  default when a reference PPTX is present.
+- `template-following`: user supplied a source/template deck whose slide
+  skeletons and visual system must be inherited.
+- `create`: no deck/template is supplied; build from prompt and sources.
+- `targeted-edit`: small changes to an existing deck.
+
+When both a source deck and a better reference deck exist, separate them:
+
+- source deck: content, required sections, facts, existing material.
+- reference deck: quality bar, rhythm, taste, and proof that a stronger output
+  is possible.
+
+Do not blindly clone the reference. Beat it by improving story precision,
+composition variety, chart clarity, whitespace, and final render quality.
+
+### Deck Profile Router
+
+After task mode, choose exactly one primary `deck-profile`. This is a hard
+routing step, not a labeling exercise. The profile determines which proof
+objects, source rules, visual density, asset rules, and QA gates are blocking.
+
+Profiles:
+
+- `finance-ir`: earnings, investor relations, operating reviews, financial
+  analysis. Requires exact reported figures, unit discipline, source footnotes,
+  bridges, tables, and disclosure logic.
+- `product-platform`: SaaS/platform/product narratives. Requires architecture
+  maps, workflow diagrams, adoption proof, product-to-financial linkage, and
+  no generic feature-card grids.
+- `gtm-growth`: GTM, marketing, consumer growth, subscription ecosystems,
+  mobility, customer engagement. Requires a visible growth loop, segment or
+  cohort proof, monetization bridge, and brand-aware rhythm.
+- `engineering-platform`: developer, AI, infrastructure, data, security, and
+  technical platform decks. Requires accurate system diagrams, technical labels
+  that survive executive simplification, and metrics tied to the architecture.
+- `strategy-leadership`: investor-day, board, transformation, and market
+  strategy decks. Requires chapter discipline, market framing, strategic bets,
+  and transition slides that carry the thesis.
+- `consumer-retail`: lookbooks, clienteling, luxury, consumer-brand, campaign,
+  travel, lifestyle, food, fashion, beauty, people, places, animals, sports,
+  playful/kids visual storytelling, and other image-led decks where the audience
+  needs to visually inspect the subject. Requires real assets or explicit asset
+  provenance, image quality, editorial hierarchy, and client-ready copy.
+- `template-following`: user supplied a template/source deck whose slides must
+  be treated as the editable starting point. Requires `template-audit.txt`,
+  `template-frame-map.json`, and `deviation-log.txt`; follow
+  `template-and-edit.md` for the exact duplicate-first starter method.
+- `targeted-edit-data`: add or edit a data/comparison slide. Requires exact
+  calculations before visual work and a native-looking insertion into the
+  existing deck.
+- `targeted-edit-media`: add headshots, logos, screenshots, or other media.
+  Requires identity/source verification, consistent crops, and preservation of
+  the source deck layout grammar.
+- `appendix-heavy`: dense appendix, tables, disclosures, or source packs.
+  Requires index/page markers, readable small-type thresholds, table grammar,
+  and explicit source-density rules.
+
+If more than one profile applies, pick the profile that creates the highest
+delivery risk as primary, then list secondary gates in the claim spine. Example:
+a finance investor deck with a supplied template is `finance-ir` primary and
+`template-following` secondary.
+
+When a profile is selected, read its corresponding file under
+`$SKILL_DIR/profiles/` if the task is substantial or unfamiliar:
+
+- `finance-ir.md`
+- `product-platform.md`
+- `gtm-growth.md`
+- `engineering-platform.md`
+- `consumer-retail.md`
+- `template-and-edit.md`
+- `appendix-heavy.md`
+
+Create `$WORKSPACE/profile-plan.txt` with:
+
+- task mode
+- primary deck-profile
+- secondary profile gates, if any
+- required proof objects
+- source/asset requirements
+- brand authenticity constraints for logos, icons, mascots, screenshots, and
+  other identity assets
+- profile-specific QA gates
+- known missing inputs
+
+## Phase 0: Source And Reference Read
+
+For every source or reference deck:
+
+- Render it to PNGs or PDF pages.
+- Make a contact sheet.
+- Extract slide text.
+- Identify which slides are content sources, which are visual targets, and
+  which patterns are anti-patterns.
+
+For source links:
+
+- Browse or otherwise retrieve the actual source page.
+- For finance/product narratives, exhaust official linked materials such as
+  earnings decks, supplements, filings, and IR PDFs before omitting customer,
+  cohort, module, bookings, retention, guidance, or mix metrics.
+- Extract exact metrics and source dates.
+- Keep links in source notes and in a quiet deck footer or appendix.
+- Never invent missing metrics to make a chart prettier.
+
+Brand authenticity gate:
+
+- Treat logos, mascots, app icons, product UI, character marks, badges, partner
+  marks, and customer marks as identity assets.
+- Do not draw, trace, approximate, or stylize a company logo, mascot, app icon,
+  or signature brand mark from scratch unless the user explicitly asks for an
+  unofficial concept.
+- Use a verified source asset with provenance, use a user-provided asset, or
+  omit the identity asset entirely.
+- When an official asset cannot be verified or embedded cleanly, rely on color,
+  typography, layout, product language, and reported metrics as brand cues
+  instead of inventing a pseudo-logo or decorative icon.
+- Record every identity asset in `$WORKSPACE/source-notes.txt` with source,
+  provenance, and why it belongs in the deck.
+- For template-following and source-deck tasks, inspect which identity assets
+  are official in the source. Preserve or borrow only verified assets; do not
+  create lookalike marks to fill visual gaps.
+
+Create:
+
+- `$WORKSPACE/source-notes.txt`
+- `$WORKSPACE/reference-audit.txt`
+- `$WORKSPACE/data.json` when metrics/charts are used
+- `$WORKSPACE/template-audit.txt` for template-following or targeted-edit modes
+- `$WORKSPACE/template-frame-map.json` for template-following or targeted-edit
+  modes
+- `$WORKSPACE/deviation-log.txt` when inheriting a source deck visual system
+- `$WORKSPACE/template-starter.pptx` when using a template PPTX as a starting
+  point
+
+For template-following and targeted-edit modes, `template-audit.txt` must include:
+
+- preserve: visual rules that must survive
+- improve: weak spots that can be upgraded
+- do not imitate: source artifacts that should not be copied
+- brand/assets: logos, colors, imagery, type, and crop language
+- insertion contract: how new slides or objects join the existing deck
+
+For exact template-following source inspection, full slide-library planning,
+duplicate-first starter deck creation, and template QA blockers, follow
+`$SKILL_DIR/profiles/template-and-edit.md`.
+
+## Phase 1: Narrative Spine
+
+Before designing, write the story as slide claims. This is binding.
+
+Every non-appendix slide must have:
+
+- a kicker: 1-3 words that names the role, e.g. `EXPANSION DRIVERS`
+- a claim title: a conclusion, not a topic label
+- a proof object: one chart, table, timeline, diagram, or visual comparison
+- a support note: concise, factual, and source-backed
+
+For finance/product narratives, a slide with only one thin chart usually fails.
+Prefer one dominant proof object plus a compact context rail, variance table, or
+callout stack when it improves the argument. Reject proof objects whose metric
+movement is too small to carry the claim unless they support a larger bridge.
+Product maps must show product-to-business linkage: module or workflow,
+adoption signal, expansion/monetization logic, or efficiency impact.
+
+Bad title: `Revenue and margin trends`
+
+Good title: `Growth slowed, but the margin engine kept expanding.`
+
+Bad title: `Expansion drivers`
+
+Good title: `Backlog is compounding faster than revenue.`
+
+If a title can be used after swapping the company name, sharpen it.
+
+Create `$WORKSPACE/claim-spine.txt` with:
+
+- thesis
+- audience
+- one-line arc
+- slide list with claim, proof object, source, and omission notes
+
+## Phase 2: Design System Lock
+
+Create `$WORKSPACE/design-system.txt` before writing slide modules.
+
+The design system must define:
+
+- slide size, usually `1280x720`
+- background system
+- typography pair using installed fonts only
+- color palette with usage rules
+- chart grammar
+- diagram grammar
+- connector grammar
+- container / box grammar
+- source/footer grammar
+- page marker grammar
+- title/kicker grammar
+- data-label grammar
+- brand asset policy and identity-asset provenance
+- allowed brand cues versus forbidden logo/icon/mascot approximations
+- allowed layout families
+- banned motifs
+
+For premium analytics decks, prefer:
+
+- warm paper or deep ink backgrounds, not default pale dashboards
+- a display serif or refined display face for claims
+- a utilitarian sans for labels
+- hairline rules instead of box outlines
+- open composition instead of repeated cards
+- direct labels on charts instead of heavy legends
+- fewer objects with stronger hierarchy
+- Kickers must align as one optical unit: marker center and label center share the
+  same y-axis, and letter-spaced all-caps labels must be vertically centered in a
+  box with enough breathing room to avoid low-looking baselines.
+- Use a canonical kicker construction rather than hand-tuning each slide:
+  - marker and label must be named as a pair, e.g. `kicker-marker` and
+    `kicker-label`, or `kicker-01-marker` and `kicker-01-label`
+  - marker and label boxes should share the same vertical center within `<= 1px`
+  - the label box must use middle vertical alignment and enough height to avoid
+    low-looking glyphs after render/export
+  - if multiple kicker rows appear on a slide, suffix the pair names consistently
+    so QA can verify each row
+
+Do not use a one-note palette. Do not let teal, navy, beige, purple, or gray
+dominate without a deliberate secondary contrast.
+
+## Phase 3: Contact-Sheet Plan
+
+Before building slides, create `$WORKSPACE/contact-sheet-plan.txt`.
+
+For a 10-slide deck, use at least 5 distinct macro-layout families, such as:
+
+- cover with metric rail
+- editorial product map
+- horizontal bar proof with margin notes
+- donut or mix proof with ranked evidence table
+- line chart with right-side KPI stack
+- sequential bar chart with side summary rail
+- two-series cash chart with margin callout
+- roadmap timeline
+- dense appendix table
+- dark appendix/source page
+
+Hard gates:
+
+- no more than 2 card-grid slides in a 10-slide deck
+- no 3 consecutive slides may share the same macro layout
+- no repeated `title + subtitle + boxed panel grid` cadence
+- no rounded card default unless the data relationship requires containment
+- no decorative boxes around prose
+
+The contact sheet must look authored before details are read.
+
+## Phase 4: Editable Build
+
+Build one ESM slide module per slide in `$SLIDES_DIR`, exporting numbered
+functions such as:
+
+```js
+export async function slide01(presentation, ctx) {
+  const slide = presentation.slides.add();
+  // editable artifact-tool presentation JSX content
+  return slide;
+}
+```
+
+Prefer native editable shapes, lines, text, tables, and chart-like constructs.
+For charts, native chart helpers are allowed, but authored editable chart
+systems built from shapes are acceptable when they give better label placement
+and visual polish.
+
+### Structured Visual Precision Contract
+
+Charts, diagrams, connectors, boxes, tables, and flows are high-risk proof
+objects. Treat them as geometry systems, not decoration.
+
+Before authoring any structured visual, define:
+
+- what the visual must prove
+- the primary reading order
+- each node / mark / series and what it means
+- each edge / connector and what relationship it encodes
+- each container / box and what grouping or containment it means
+- the intended alignment, spacing, and label attachment rules
+
+Hard build rules:
+
+- Connected series must be rendered as one continuous editable path or as a
+  verified native chart series. Do not fake a line with separately rotated
+  rectangles, disconnected strokes, floating slashes, or decorative arrows.
+- Every connected series must pass through its intended markers and preserve
+  the correct point order after render/export.
+- In diagrams, connectors must visibly attach to the correct source and target,
+  follow the intended direction, avoid unrelated objects, and terminate cleanly
+  without ambiguous crossings.
+- Do not use arrows unless directionality matters. If direction matters, arrow
+  heads must be consistent, legible, and semantically meaningful.
+- Boxes must imply a real grouping, comparison, lane, stage, or containment
+  relationship. Remove containers that only decorate prose.
+- Equal-role boxes must share exact height, alignment, padding, border logic,
+  and text treatment unless the hierarchy intentionally differs.
+- Text inside boxes must have enough padding and never sit against edges,
+  collide with rules, or rely on shrink-to-fit as the default.
+- Use a minimum `12px` vertical interior padding for boxed prose / callouts and
+  `16px` when the box carries 2+ lines or dark-background copy. If a box only
+  looks correct with near-zero bottom room, enlarge the box or shorten the copy.
+- Any text that starts inside a filled callout / metric container and spills
+  past that container edge is a hard failure, even if the overflowed line is no
+  longer classified as an in-box child by a layout script.
+- Labels must anchor to the mark, series, box, or connector they describe. A
+  viewer should never need to guess which label belongs to which object.
+- Repeated metric rails / KPI stacks must preserve their full grammar on every
+  item: if the pattern is `value + label + context`, every item must visibly
+  render all three pieces with adequate contrast against its background.
+- Preview-visible defects override layout-script silence: orphan labels, missing
+  values in a repeated metric pattern, markers sitting on top of copy, or any
+  object that looks obviously accidental at full size must be treated as a build
+  failure even when export and layout checks succeed.
+- Tables and matrices must preserve row/column grammar under thumbnail review:
+  headers, baselines, alignment, and emphasis must remain visually consistent.
+- If a chart or diagram requires too many exceptions to remain clear, rebuild
+  it with a simpler visual rather than patching around geometry defects.
+
+artifact-tool presentation JSX chart caveat:
+
+- Try native `slide.charts.add(...)` when the API can represent the chart.
+- Always verify the exported PPTX package for `ppt/charts/chart*.xml`.
+- If native chart parts are not preserved, or export throws `toProto` /
+  `setChangeHandler` errors, switch to authored editable chart primitives
+  rather than shipping weak native charts.
+- Do not style `chart.yAxis.majorGridlines` unless freshly
+  verified; it can fail export with `this[#h].toProto is not a function`.
+- Do not fake per-point bar colors by adding zero-valued helper series. If
+  native charts cannot express the visual cleanly, rebuild the chart with
+  editable shapes and direct labels.
+- For line, trend, or connected-series visuals, prefer a verified native line
+  chart when the API can express the chart cleanly. If authored with
+  primitives, draw the series as one continuous editable custom path / polyline
+  through the data points.
+- Do not construct a line series from individually rotated rectangles or short
+  segment shapes; these can export as detached slashes or broken pseudo-arrows.
+- Record the choice in `$WORKSPACE/qa/comeback-scorecard.txt`.
+
+Use helper scripts copied with this skill:
+
+```bash
+node "$SKILL_DIR/scripts/render_artifact_slide.mjs" \
+  --workspace "$WORKSPACE" \
+  --slide-module "$SLIDES_DIR/slide-01.mjs" \
+  --output "$PREVIEW_DIR/slide-01.png" \
+  --layout "$LAYOUT_DIR/slide-01.layout.json"
+
+node "$SKILL_DIR/scripts/build_artifact_deck.mjs" \
+  --workspace "$WORKSPACE" \
+  --slides-dir "$SLIDES_DIR" \
+  --out "$FINAL_PPTX" \
+  --preview-dir "$PREVIEW_DIR" \
+  --layout-dir "$LAYOUT_DIR/final" \
+  --contact-sheet "$PREVIEW_DIR/contact-sheet.png" \
+  --slide-count <n>
+```
+
+Presentation JSX source must resolve through artifact-tool. Do not bypass the
+bundled runtime with unrelated package imports.
+
+Editable primitives are encouraged for charts, diagrams, and abstract product
+flows. They are not a license to fabricate brand marks. Do not create
+brand-like icons, mascots, app marks, partner marks, or pseudo-logos as
+decoration or to fill whitespace. If the asset is not verified, solve the slide
+with stronger hierarchy, data, copy, or abstract shapes instead.
+
+## Phase 5: Comeback Rubric
+
+Score the rendered contact sheet and full-size slides in
+`$WORKSPACE/qa/comeback-scorecard.txt`.
+
+Each dimension is 0-5:
+
+- `story`: titles are claims; sequence has a real arc
+- `specificity`: deck would fail the noun-swap test
+- `rhythm`: contact sheet has varied macro layouts
+- `whitespace`: slides breathe without feeling empty
+- `chart clarity`: charts prove one sentence, labels are direct, and geometry is
+  continuous / correctly attached
+- `typography`: type feels intentional, not default
+- `restraint`: no filler boxes, badges, or decorative clutter
+- `precision`: metrics and source notes are exact
+- `coherence`: one visual system across the deck
+- `reference delta`: visibly better than the target reference, when supplied
+
+Required minimum before delivery:
+
+- total score >= 44 / 50 when a reference is supplied; otherwise >= 40 / 45
+- no dimension below 4
+- `reference delta` >= 4 when a reference is supplied; otherwise mark it `n/a`
+  and do not claim reference-beating
+
+Profile gates are pass/fail and sit above the numeric rubric. A deck fails even
+with a high visual score if the profile gate fails. Common profile blockers:
+
+- `finance-ir`: invented or unsupported metrics, mixed units, missing footnotes,
+  or charts that look good but do not reconcile to sources.
+- `product-platform`: generic feature cards, architecture boxes that say
+  nothing, module lists without adoption or monetization proof, or missing
+  adoption/business linkage.
+- `gtm-growth`: funnel labels without progression logic, weak brand fit,
+  fabricated brand marks, or monetization claims unsupported by proof.
+- `engineering-platform`: technically vague diagrams, labels stripped of real
+  meaning, or developer details that overwhelm the executive story.
+- `strategy-leadership`: chapter dividers without thesis movement or a market
+  frame that never returns in the operating plan.
+- `consumer-retail`: stock-looking imagery, weak crop quality, unverified asset
+  provenance, or client outreach copy that feels generic.
+- `template-following`: a theme-matched fresh layout, source-slide frame drift,
+  or style drift without an explicit deviation reason.
+- `targeted-edit-data`: calculation mistakes, wrong ranking, or a new slide
+  that looks pasted in.
+- `targeted-edit-media`: unverified identities, inconsistent headshot crops, or
+  local layout damage.
+- `appendix-heavy`: unreadable tables, missing index, or source density that
+  hides the answer.
+- `brand authenticity`: fabricated logo, mascot, app icon, signature mark,
+  unverified product UI, or pseudo-official mark used as decoration.
+
+If a reference deck is supplied, write a blunt slide-by-slide comparison:
+
+- where this deck beats the reference
+- where the reference still wins
+- what changed after iteration
+
+## Phase 6: Mechanical Verification
+
+Before final delivery:
+
+- Confirm the final PPTX exists and is non-empty.
+- Confirm the expected slide count in the package.
+- Confirm no empty media files.
+- Confirm chart package parts when native charts are required, or document why
+  authored editable chart primitives were used instead.
+- Render every final slide to PNG through artifact-tool.
+- Inspect the artifact-tool contact sheet at thumbnail size and the
+  full-size PNG renders for visual errors.
+- During full-size render review, explicitly verify repeated UI grammars such as
+  KPI rails, step sequences, legends, and forecast strips for completeness and
+  contrast: no blank value slots, no same-color-on-background text, and no
+  decorative marks that collide with the reading path.
+- For every chart, diagram, matrix, connector system, and box system, inspect
+  the rendered slide at full size and verify the intended geometry:
+  - connected lines are continuous and pass through the correct markers
+  - bars / dots / labels align to the same baseline or axis logic
+  - arrows and connectors attach to the intended objects and do not float
+  - arrows point in the intended reading direction
+- boxes that share a role line up, carry equivalent padding, and do not clip
+    or crowd text
+- kickers / eyebrow rows align optically: icon, rule, and label sit on one
+    centerline rather than a low or drifting text baseline
+- Use the kicker naming convention so layout QA can verify centerline alignment;
+  un-named kicker rows are a QA gap, not a pass.
+- boxed prose and callouts keep visible top/bottom breathing room, especially on
+    dark fills and multi-line statements
+  - grouped objects read as a coherent system at thumbnail size
+- Inspect the contact sheet and full-size renders for unofficial logos, app
+  icons, mascots, product UI, partner marks, and customer marks. Confirm each
+  identity asset is verified in source notes or remove it.
+- Do not require, bundle, or assume LibreOffice or any other external renderer.
+  If a compatible renderer is already available and the user asks for it, it may
+  be used as non-blocking extra QA only.
+- Run layout checks and fix all errors. Warnings may remain only when they are
+  known false positives from intentional table/axis/label construction and the
+  rendered slide is clean.
+- Deficient box padding and text overflow out of filled callouts are errors, not
+  acceptable warnings.
+
+## Phase 7: Final QA Ledger
+
+Create `$WORKSPACE/qa/comeback-scorecard.txt` with:
+
+- final score by rubric dimension
+- primary deck-profile and profile gate pass/fail
+- reference-deck comparison
+- tool/runtime caveats
+- package checks
+- render checks
+- accepted warnings or tradeoffs
+
+Do not leave the scorecard as vague praise. It should name the remaining weak
+spots if any exist.
+
+## Blocking Anti-Patterns
+
+Fix these before delivery:
+
+- title states a topic instead of a conclusion
+- slide uses more than one dominant evidence object
+- chart has a legend when direct labels would work better
+- chart displays data but does not prove the title
+- connected-series chart is rendered as detached strokes, floating slashes,
+  pseudo-arrows, or a path that misses its markers
+- line or connector geometry changes meaning after render / export
+- connector floats, attaches to the wrong object, crosses unrelated structure,
+  or points in an ambiguous direction
+- arrows are decorative rather than semantic
+- box system implies grouping that the content does not support
+- equal-role boxes are visibly misaligned, inconsistently padded, or styled as
+  if they have different meanings
+- label appears visually detached from the mark, series, connector, or box it
+  describes
+- a repeated KPI / metric rail omits a required value, label, or context line on
+  any item
+- a marker, node, glyph, or accent shape visibly sits on top of readable copy
+- a value is technically present but visually lost because it has insufficient
+  contrast against the background
+- table or matrix loses its row / column grammar at thumbnail size
+- proof object is too thin to carry the claim
+- product or architecture diagram lacks adoption, monetization, expansion, or
+  efficiency linkage
+- visible containers are louder than the content
+- rounded cards are used as default scaffolding
+- three slides in a row share the same composition
+- contact sheet reads as a template pack
+- contact sheet has clean slides but weak information architecture
+- body copy exists only to fill space
+- appendix is clean but unreadable
+- artifact-tool render has obvious wrapped labels, collisions, awkward vertical
+  text, or cramped callouts
+- footer/source/page marker changes style
+- kicker icon and label are not optically centered on the same row
+- kicker rows are hand-built without named marker/label pairs, preventing QA
+  from verifying their alignment
+- boxed prose appears pinned to the bottom edge or lacks visible vertical
+  breathing room
+- typography falls back to default without intent
+- low-resolution logo or rough image crop
+- fabricated or approximated official logo, mascot, app icon, product UI, or
+  signature brand mark
+- brand-like icon used just to fill whitespace
+- unprovenanced partner/customer logos, product screenshots, or brand badges
+- unsupported metric or vague source label
+- output only matches the reference instead of beating it
+
+## Iteration Rule
+
+Do not stop after the first export unless the comeback rubric passes. Iterate
+the weakest 2-4 slides first, then rerender the full deck. Prefer a bold rebuild
+of a weak slide over cosmetic nudge work.
+
+If a model or tool cannot reach the reference quality, say exactly why and name
+the remaining weakest slides. Do not call the deck done because a PPTX exists.
+
+## Subagents
+
+Subagents are allowed when the user explicitly asks for them. Use them for:
+
+- source metric extraction
+- reference deck critique
+- QA scoring
+- appendix implementation from a fixed spec
+- alternate prototype generation in a separate workspace
+
+The main agent owns final story, visual system, integration, and QA. Never ship
+a raw stitched deck from independent slide workers.
+
+## Matrix Battle Harness
+
+Use this harness when validating or improving the skill across many prompts.
+It creates deck-quality probes, not source-complete final decks, unless all
+attachments and source data are available. The probe output is for stress
+testing profile routing, visual grammar, proof-object quality, and QA gates.
+
+Command:
+
+```bash
+node "$SKILL_DIR/scripts/run_prompt_battle.mjs" \
+  --prompts "$WORKSPACE/batch-prompts/slides_prompts_first25.json" \
+  --workspace "$WORKSPACE/batch-runs/full-25" \
+  --limit 25 \
+  --scale 0.55
+```
+
+The harness writes:
+
+- one editable PPTX per prompt
+- PNG previews for every slide
+- per-prompt contact sheets
+- aggregate first-slide and proof-object contact sheets
+- `battle-summary.json`
+- `battle-summary.txt`
+
+After a battle run:
+
+- run layout checks across every `layout/` directory
+- confirm every PPTX has the expected slide count
+- confirm no empty media files
+- inspect aggregate contact sheets for sameness
+- update this skill when repeated failures show a missing gate
+
+Do not confuse a battle probe with a final customer deck. For final delivery,
+rerun the normal workflow with the actual source attachments, exact metrics,
+real imagery, and full reference comparison.
+
+## Final Delivery
+
+After the final PPTX is exported and verified, run the cleanup helper:
+
+```bash
+node "$SKILL_DIR/scripts/cleanup_presentation_workspace.mjs" \
+  --workspace "$WORKSPACE" \
+  --output-dir "$OUTPUT_DIR"
+```
+
+The cleanup helper preserves final `.pptx` deliverables in `$OUTPUT_DIR` and
+deletes scratch artifacts from the current thread-scoped `$WORKSPACE`:
+
+- Delete generated planning and QA text notes such as `profile-plan.txt`,
+  `source-notes.txt`, `reference-audit.txt`, `claim-spine.txt`,
+  `design-system.txt`, `contact-sheet-plan.txt`, `battle-summary.txt`, and
+  `$WORKSPACE/qa/*.txt`.
+- Delete generated reference/imagegen prompt text files such as
+  `*.imagegen.txt` and `reference-imagegen-prompts.txt`.
+- Delete rendered review artifacts such as `contact-sheet.png`, preview PNGs,
+  temporary reference PNGs, and other temporary images that are not deliberately
+  embedded in the final deck.
+- Delete generated per-run scripts and slide modules, including files under
+  `$SLIDES_DIR`. Do not delete the installed skill helper scripts under
+  `$SKILL_DIR/scripts`.
+- Delete generated layout JSON, build manifests, and other per-run scratch
+  metadata.
+- Do not delete user-provided source files, source decks, or assets that are
+  intentionally embedded in or required to regenerate the final deck.
+- If the user explicitly asks for QA artifacts, keep only the requested
+  artifacts and mention that they were retained.
+- Never delete sibling folders under `outputs/$THREAD_ID/presentations/` or any
+  other thread's workspace.
+
+If `$OUTPUT_DIR` is outside `$WORKSPACE`, the cleanup helper deletes
+`$WORKSPACE` and does not clean the external output directory. That external
+directory must contain only final deliverables, not scratch artifacts.
+
+Do not attach or link `contact-sheet.png`, preview PNGs, generated scripts,
+planning docs, JSON manifests, layout JSON, imagegen prompt files, or temporary
+images unless the user explicitly asks for QA artifacts.
+Do not mention that scratch or QA artifacts were cleaned up in the final
+response; the final response should focus on the user-facing deck only.
+
+Deliver:
+
+- final `.pptx` with a relevant deck-title filename, not a generic name such
+  as `output.pptx` or `deck.final.pptx`
+- brief scorecard summary
+- note any residual gap against the reference
+
+The final response should be short and artifact-focused.