Pitfalls observed in real Generate-PPTX runs. Each row = symptom + actual fix.
SVG → PPTX converter hard rules
#
Symptom
Actual fix
1
<line> element rejected: "cannot use filter; supported native targets are rect, circle, path, and text"
Strip filter="url(#glow)" from <line> and <polyline>. Convert arrows to <path d="M x y L x y L x y Z"/> with a triangle tail.
2
spec_lock typography-size recurrence: undeclared font-size N (M occurrences) exceeds the sparse-display limit
Every recurring font size must be declared in spec_lock.md## typography as a lowercase snake_case role with px anchor. M > 2 occurrences triggers the error. Audit all SVG font-size="N" values and map them into declared roles (body=24, title=42, subtitle=32, annotation=18, footnote=14).
3
Pattern fills like <pattern id="gridp"> render as ltUpDiag diagonal lines in the exported PPTX
The converter falls back to a generic pattern. Replace with explicit per-line <line x1=...> elements (40px grid × N+1 lines). Costs ~80 SVG elements but guarantees faithful export.
4
XML well-formedness error: not well-formed (invalid token)
Bare & in text breaks SVG. Always run text through html.escape(s, quote=True) before insertion. Common offenders: ampersand, HTML entity names like /—, smart quotes if not raw Unicode.
Section heading MUST exactly match ^X\. Speaker Notes (Requirements|Plan|Strategy)$.
6
design_spec.md schema: content outline has no Slide blocks
Slide blocks MUST use #### Slide NN - (4 hashes, 2-digit zero-padded number, no "P" prefix). The "P" prefix or ### Slide PNN will silently fail to match.
7
spec_lock canvas viewBox is required
## canvas section MUST include both viewBox: 0 0 W H and format: PPT 16:9 (or other named format).
8
Master export requires spec_lock.md typography rows: title, body
## typography section MUST include title_family AND body_family as separate roles, plus font_family for backwards compatibility.
Delegated research pitfall
#
Symptom
Actual fix
9
Three parallel research subagents all hit 600s timeout with no file written
Subagents waste turns on web_extract round-trips. Never delegate "produce markdown report" as one task. Either (a) dispatch ≤3 sites each with a hard line cap, or (b) run web fetches in the main agent via urllib/curl and assemble the markdown yourself. Do not retry the same subagent shape.
Environment / setup
#
Symptom
Actual fix
10
confirm UI server fails to start with flask not found
System Python may be PEP-668. Build a venv with uv venv /tmp/ppt-env --python 3.13 && uv pip install --python /tmp/ppt-env/bin/python flask python-pptx Pillow uharfbuzz skia-pathops XlsxWriter. All ppt-master scripts must be invoked via /tmp/ppt-env/bin/python, not system python.
The wheel installs as pathops module, not skia_pathops. import pathops works. Do not waste cycles fixing the import name — write code against pathops.
User delegation patterns
#
Symptom
Actual fix
12
User delegates the entire 3-stage Confirm UI flow and says "继续到底"
Write all 3 stage JSONs + result.json with status: confirmed and mode: user-delegated in one pass. The blocked gates are skipped only when the user explicitly grants delegation — re-confirm wording if ambiguous.
13
User says "你搜太慢了 / 直接告诉我要搜什么"
Stop autonomous fetching. Emit a structured task list (file name → target page → official source URL → required spec) so the user can drop assets into a known path. Do not loop on slow fetches.
Visual review pitfalls
#
Symptom
Actual fix
14
Low-DPI vision-model review flags "标题被表格遮挡/截断" that ground-truth XML shows is impossible
Always cross-check vision review against actual <a:off x y> and <a:ext cx cy> in ppt/slides/slideN.xml. Low-DPI render + vision OCR produces false positives for Chinese glyphs; the PPTX XML is ground truth.
15
Page-by-page visual review loops forever at low DPI
Use LibreOffice → PDF → pdftoppm -r 150 for high-DPI raster, then vision-analyse cropped regions. Default 60 DPI is too lossy for Chinese glyph metrics.
Topic research gate
#
Symptom
Actual fix
16
Topic-only research gate fires repeatedly
Run the bounded research once per topic-research.md and capture results in sources/*.md. Treat the resulting markdown as content authority; do not re-research every Confirm UI round.
1---2name: ppt-master-execution-pitfalls3description: Use when running ppt-master Generate-PPTX routes.4---56# ppt-master Execution Pitfalls78Pitfalls observed in real Generate-PPTX runs. Each row = symptom + actual fix.910## SVG → PPTX converter hard rules1112| # | Symptom | Actual fix |13|---|---|---|14| 1 | `<line>` element rejected: "cannot use filter; supported native targets are rect, circle, path, and text" | Strip `filter="url(#glow)"` from `<line>` and `<polyline>`. Convert arrows to `<path d="M x y L x y L x y Z"/>` with a triangle tail. |15| 2 | `spec_lock typography-size recurrence: undeclared font-size N (M occurrences) exceeds the sparse-display limit` | Every recurring font size must be declared in `spec_lock.md` `## typography` as a lowercase snake_case role with px anchor. M > 2 occurrences triggers the error. Audit all SVG `font-size="N"` values and map them into declared roles (body=24, title=42, subtitle=32, annotation=18, footnote=14). |16| 3 | Pattern fills like `<pattern id="gridp">` render as `ltUpDiag` diagonal lines in the exported PPTX | The converter falls back to a generic pattern. Replace with explicit per-line `<line x1=...>` elements (40px grid × N+1 lines). Costs ~80 SVG elements but guarantees faithful export. |17| 4 | XML well-formedness error: `not well-formed (invalid token)` | Bare `&` in text breaks SVG. Always run text through `html.escape(s, quote=True)` before insertion. Common offenders: ampersand, HTML entity names like ` `/`—`, smart quotes if not raw Unicode. |1819## spec_lock.md schema traps2021| # | Symptom | Actual fix |22|---|---|---|23| 5 | `design_spec.md schema: missing section 'speaker_notes'` | Section heading MUST exactly match `^X\. Speaker Notes (Requirements\|Plan\|Strategy)$`. |24| 6 | `design_spec.md schema: content outline has no Slide blocks` | Slide blocks MUST use `#### Slide NN -` (4 hashes, 2-digit zero-padded number, no "P" prefix). The "P" prefix or `### Slide PNN` will silently fail to match. |25| 7 | `spec_lock canvas viewBox is required` | `## canvas` section MUST include both `viewBox: 0 0 W H` and `format: PPT 16:9` (or other named format). |26| 8 | `Master export requires spec_lock.md typography rows: title, body` | `## typography` section MUST include `title_family` AND `body_family` as separate roles, plus `font_family` for backwards compatibility. |2728## Delegated research pitfall2930| # | Symptom | Actual fix |31|---|---|---|32| 9 | Three parallel research subagents all hit 600s timeout with no file written | Subagents waste turns on `web_extract` round-trips. Never delegate "produce markdown report" as one task. Either (a) dispatch ≤3 sites each with a hard line cap, or (b) run web fetches in the main agent via `urllib`/`curl` and assemble the markdown yourself. Do not retry the same subagent shape. |3334## Environment / setup3536| # | Symptom | Actual fix |37|---|---|---|38| 10 | confirm UI server fails to start with `flask not found` | System Python may be PEP-668. Build a venv with `uv venv /tmp/ppt-env --python 3.13 && uv pip install --python /tmp/ppt-env/bin/python flask python-pptx Pillow uharfbuzz skia-pathops XlsxWriter`. All ppt-master scripts must be invoked via `/tmp/ppt-env/bin/python`, not system python. |39| 11 | `skia-pathops` import fails despite "audited" success message | The wheel installs as `pathops` module, not `skia_pathops`. `import pathops` works. Do not waste cycles fixing the import name — write code against `pathops`. |4041## User delegation patterns4243| # | Symptom | Actual fix |44|---|---|---|45| 12 | User delegates the entire 3-stage Confirm UI flow and says "继续到底" | Write all 3 stage JSONs + `result.json` with `status: confirmed` and `mode: user-delegated` in one pass. The blocked gates are skipped only when the user explicitly grants delegation — re-confirm wording if ambiguous. |46| 13 | User says "你搜太慢了 / 直接告诉我要搜什么" | Stop autonomous fetching. Emit a structured task list (file name → target page → official source URL → required spec) so the user can drop assets into a known path. Do not loop on slow fetches. |4748## Visual review pitfalls4950| # | Symptom | Actual fix |51|---|---|---|52| 14 | Low-DPI vision-model review flags "标题被表格遮挡/截断" that ground-truth XML shows is impossible | Always cross-check vision review against actual `<a:off x y>` and `<a:ext cx cy>` in `ppt/slides/slideN.xml`. Low-DPI render + vision OCR produces false positives for Chinese glyphs; the PPTX XML is ground truth. |53| 15 | Page-by-page visual review loops forever at low DPI | Use LibreOffice → PDF → `pdftoppm -r 150` for high-DPI raster, then vision-analyse cropped regions. Default 60 DPI is too lossy for Chinese glyph metrics. |5455## Topic research gate5657| # | Symptom | Actual fix |58|---|---|---|59| 16 | Topic-only research gate fires repeatedly | Run the bounded research once per `topic-research.md` and capture results in `sources/*.md`. Treat the resulting markdown as content authority; do not re-research every Confirm UI round.
Run npx skillmds@latest add publieople/ppt-master-execution-pitfalls in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Use when running ppt-master Generate-PPTX routes. It is listed under Docs & Writing on SkillMD.
This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
publieople (@publieople) published this skill. Their other Agent Skills are listed on their SkillMD profile.
publieople