Initial commit: add all skills files

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

pptx-generator/references/pitfalls.md

@@ -0,0 +1,112 @@
+# QA Process & Common Pitfalls
+
+## QA Process
+
+**Assume there are problems. Your job is to find them.**
+
+Your first render is almost never correct. Approach QA as a bug hunt, not a confirmation step. If you found zero issues on first inspection, you weren't looking hard enough.
+
+### Content QA
+
+```bash
+python -m markitdown output.pptx
+```
+
+Check for missing content, typos, wrong order.
+
+**Check for leftover placeholder text:**
+
+```bash
+python -m markitdown output.pptx | grep -iE "xxxx|lorem|ipsum|placeholder|this.*(page|slide).*layout"
+```
+
+If grep returns results, fix them before declaring success.
+
+### Verification Loop
+
+1. Generate slides -> Extract text with `python -m markitdown output.pptx` -> Review content
+2. **List issues found** (if none found, look again more critically)
+3. Fix issues
+4. **Re-verify affected slides** — one fix often creates another problem
+5. Repeat until a full pass reveals no new issues
+
+**Do not declare success until you've completed at least one fix-and-verify cycle.**
+
+### Per-Slide QA (for from-scratch creation)
+
+```bash
+python -m markitdown slide-XX-preview.pptx
+```
+
+Check for missing content, placeholder text, missing page number badge.
+
+---
+
+## Common Mistakes to Avoid
+
+- **Don't repeat the same layout** — vary columns, cards, and callouts across slides
+- **Don't center body text** — left-align paragraphs and lists; center only titles
+- **Don't skimp on size contrast** — titles need 36pt+ to stand out from 14-16pt body
+- **Don't default to blue** — pick colors that reflect the specific topic
+- **Don't mix spacing randomly** — choose 0.3" or 0.5" gaps and use consistently
+- **Don't style one slide and leave the rest plain** — commit fully or keep it simple throughout
+- **Don't create text-only slides** — add images, icons, charts, or visual elements; avoid plain title + bullets
+- **Don't forget text box padding** — when aligning lines or shapes with text edges, set `margin: 0` on the text box or offset the shape to account for padding
+- **Don't use low-contrast elements** — icons AND text need strong contrast against the background
+- **NEVER use accent lines under titles** — these are a hallmark of AI-generated slides; use whitespace or background color instead
+- **NEVER use "#" with hex colors** — causes file corruption in PptxGenJS
+- **NEVER encode opacity in hex strings** — use the `opacity` property instead
+- **NEVER use async/await in createSlide()** — compile.js won't await
+- **NEVER reuse option objects across PptxGenJS calls** — PptxGenJS mutates objects in-place
+
+---
+
+## Critical Pitfalls — PptxGenJS
+
+### NEVER use async/await in createSlide()
+
+```javascript
+// WRONG - compile.js won't await
+async function createSlide(pres, theme) { ... }
+
+// CORRECT
+function createSlide(pres, theme) { ... }
+```
+
+### NEVER use "#" with hex colors
+
+```javascript
+color: "FF0000"      // CORRECT
+color: "#FF0000"     // CORRUPTS FILE
+```
+
+### NEVER encode opacity in hex strings
+
+```javascript
+shadow: { color: "00000020" }              // CORRUPTS FILE
+shadow: { color: "000000", opacity: 0.12 } // CORRECT
+```
+
+### Prevent text wrapping in titles
+
+```javascript
+// Use fit:'shrink' for long titles
+slide.addText("Long Title Here", {
+  x: 0.5, y: 2, w: 9, h: 1,
+  fontSize: 48, fit: "shrink"
+});
+```
+
+### NEVER reuse option objects across calls
+
+```javascript
+// WRONG
+const shadow = { type: "outer", blur: 6, offset: 2, color: "000000", opacity: 0.15 };
+slide.addShape(pres.shapes.RECTANGLE, { shadow, ... });
+slide.addShape(pres.shapes.RECTANGLE, { shadow, ... });
+
+// CORRECT - factory function
+const makeShadow = () => ({ type: "outer", blur: 6, offset: 2, color: "000000", opacity: 0.15 });
+slide.addShape(pres.shapes.RECTANGLE, { shadow: makeShadow(), ... });
+slide.addShape(pres.shapes.RECTANGLE, { shadow: makeShadow(), ... });
+```