feat(pptx-skill): reliability fixes — deck-first build order, context discipline, pack-early (#13104)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

backend/onyx/skills/builtin/pptx/SKILL.md

@@ -19,6 +19,42 @@ license: Proprietary. LICENSE.txt has complete terms
 
 ---
 
+## Build Order (required)
+
+**A complete, text-viable deck must exist in `outputs/` before any asset
+enhancement.** The worst outcome is a turn that ends with no deck at all.
+
+1. **Draft**: full deck — all slides, titles, text content, layout structure —
+   written and saved to `outputs/<name>.pptx`. On the template-editing path
+   this means an EARLY first clean+pack (see [editing.md](editing.md)): edits
+   stranded in `outputs/unpacked/` deliver nothing.
+2. **Enhance in passes** (charts, icons), re-saving the deck after each pass.
+3. **Lint + QA** last (see QA below).
+
+If time or context is running short at any point, stop enhancing and ship the
+current saved deck. Never spend the start of a turn generating or inspecting
+assets for a deck that doesn't exist yet.
+
+## Reading Source Materials (context discipline)
+
+Read attached/source documents as **text** (`python -m markitdown file.pdf`).
+**Never `view_image` source pages or figure crops** — image reads exhaust the
+model context in a handful of pages and the turn dies before the deck is
+built. To reuse figures from a source PDF, extract the embedded images
+directly — no rendering, no cropping, no visual inspection:
+
+```bash
+mkdir -p outputs/figs/
+pdfimages -png -p source.pdf outputs/figs/fig   # fig-<page>-<n>.png per image
+python -c "from PIL import Image; import glob; [print(p, Image.open(p).size) for p in sorted(glob.glob('outputs/figs/*.png'))]"
+```
+
+Pick figures by page number and pixel size (real figures are large; icons and
+logos are small), place them directly, and verify them in the rendered-slide
+QA pass at the end — never by viewing each extraction.
+
+---
+
 ## Choosing a Template (do this first)
 
 Starting from a well-designed template produces far better decks than building from scratch. There are **two distinct sources** of templates — check both:

backend/onyx/skills/builtin/pptx/editing.md

@@ -38,12 +38,17 @@ When using an existing presentation as a template:
    - Reorder slides in `<p:sldIdLst>`
    - **Complete all structural changes before step 5**
 
-5. **Edit content**: Update text in each `slide{N}.xml`.
+5. **First pack (do this EARLY)**: as soon as the structure is set and first-pass content is in, clean + pack so a viewable deck exists:
+   ```bash
+   python .opencode/skills/pptx/scripts/clean.py outputs/unpacked/
+   python .opencode/skills/pptx/scripts/office/pack.py outputs/unpacked/ outputs/output.pptx --original template.pptx
+   ```
+   A turn that ends with edits stranded in `outputs/unpacked/` delivers **nothing** — the packed `.pptx` is the deliverable (SKILL.md → Build Order). Never do fine-grained restyling before the first pack exists.
+
+6. **Refine content**: update text in each `slide{N}.xml`.
    **Use subagents here if available** — slides are separate XML files, so subagents can edit in parallel.
 
-6. **Clean**: `python .opencode/skills/pptx/scripts/clean.py outputs/unpacked/`
-
-7. **Pack**: `python .opencode/skills/pptx/scripts/office/pack.py outputs/unpacked/ outputs/output.pptx --original template.pptx`
+7. **Re-clean + re-pack after each batch of edits** (same commands as step 5) — the packed deck in `outputs/` should always reflect your latest good state.
 
 ---