Humanize PPT

Humanize PPT

Use this skill when a user wants to turn raw material, notes, voice transcripts, documents, or links into a presentation-ready outline and per-page media decisions before delegating rendering to a downstream skill. Old PPT/PPTX files are not read directly: extract their text first (see scripts/pptx_qa.py's dump/inspect output), then feed that text in as --source. A deck Humanize PPT already rendered goes through --qa-from <rendered.pptx> instead — the presentation checkup, not brief mode.

Positioning

Humanize PPT is a presentation system, born for the talk: an Outline Director (AST audience-state-transfer — every page turn moves the audience forward), a Per-Page Visual-Enhancement Director (real image / SVG diagram / Remotion video), a Production Brief Orchestrator, a Presentation Checkup Runner (演讲体检; formerly the QA loop, CLI flag still --qa-from), and a Presenter-Mode hand-off. The motivation: HTML-PPT template skills are great at concept display but blow a simple idea into a dozen pretty pages, while a real 90-minute talk is ~30 — the pretty shell outruns the content density. Humanize closes that gap: it keeps the beauty (rendered natively by the downstream template skill) and makes it presentable — a line you can stand up and deliver. Downstream template skills own "renders beautifully"; Humanize owns "it's a talk, and someone checked it."

The presentation checkup in one sentence: it does not grade beauty, it grades the outline. It compares every rendered page against its outline page, pulls out the pages that can only be looked at but not spoken from, and keeps going until every page is one the speaker can stand up and present. A failed page, in plain words: a page that holds only a few words and never finishes its point, or a page that fails the audience state transfer it promised (the listener walks out of that page in the same state they walked in). Such a page should not exist; the checkup pulls it out and generates fix instructions.

Humanize is broadly compatible with downstream renderers that can consume plain markdown + JSON. Verified routes are: Chinese HTML → guizang-ppt-skill; English HTML → frontend-slides / beautiful-html-templates; native editable PowerPoint → ppt-master. Other downstreams remain hot-pluggable; support levels live in registry/renderer_registry.json and move only on real output.

It runs before downstream PPT / HTML slide skills and around the post-render presentation checkup. It owns the AST contract, the per-page media decision (does this page need a photo, a system diagram, a 10-second process clip, nothing?), the production brief that the next agent consumes, and the checkup pass on rendered HTML/PPTX. It does not own the rendered deck itself.

There are two human review gates before rendering: the outline preview and the renderer's style gate. HTML routes use Humanize's ≥4 real-cover --style-gallery. PPT Master already owns a mandatory three-stage Confirm UI with native visual previews, so --renderer ppt-master --style-gallery delegates to that gate and writes style_gallery_plan.json + commands/style-gallery/ppt-master-confirm-ui.md rather than duplicating the catalog.

The user calls Humanize PPT once for the brief, hands the brief to a downstream skill for native rendering, then calls Humanize again with --qa-from <rendered.html|native.pptx> to run the 3-iteration presentation checkup. Each iteration writes qa_report.md, fix_prompt.md, and qa_iteration.json. After 3 rounds with remaining failures, status flips to needs-human.

Humanize PPT never copies a downstream skill's template, never injects custom sections into it, and never post-processes rendered HTML or PPTX. Fixes return to the downstream author source. See references/guizang-production-brief-orchestrator.md and adapters/ppt-master-bridge-notes.md.

For public positioning, describe Humanize PPT as a brief orchestrator that pairs with native downstream renderers. Do not frame it as a renderer itself, and do not present it as a "router" that picks the best visual style for the user — that decision lives in the brief, the downstream skill's own templates, and the human's review. When a user only wants a pretty template page, that is a rendering-skill job, not a Humanize job: state the choice, not a prohibition.

AST theory

AST means Audience-State-Transfer.

• Audience: who is listening, what they know, what they resist, and why they would keep listening.
• State: the audience state before and after the deck, plus the core tension that blocks the transition.
• Transfer: the slide-by-slide path that moves the audience from initial state to desired state.

Core sentence:

PPT is not an information container. PPT is an audience state-transfer artifact.

Required output contract

For every Humanize PPT run, produce:

1. deck_brief.md — audience, goal, tension, success criteria.
2. ast_outline.md — AST map and narrative arc.
3. slide_plan.json — slide-by-slide plan, with per-page media: {image, diagram, video} decision and layout_hint.
4. speaker_intent.md — what the speaker should do on each slide. Downstream skills consume this as the source for their native speaker notes and presenter shell.
5. asset_manifest.md — Humanize's per-page material decisions: which page needs which kind of asset (image / diagram / video) and for what purpose.
6. video_slots.json — optional Remotion / HyperFrames / native video insertion plan.
7. style_brief.md — visual principle for downstream production.
8. renderer_registry.json — renderer capability snapshot for this run.
9. router_plan.json — selected primary renderer and staged route plan.
10. commands/*.md — bounded instructions for each downstream specialist agent.
11. run_manifest.json — final file inventory, route status, and QA status.
12. <renderer>-production-prompt.md — the downstream entrypoint. In addition to the HTML routes, ppt-master emits ppt-master-production-prompt.md + self-contained ppt-master-source.md and disposable outputs/ppt-master-handoff/ copies.
13. outputs/qa/qa_report.md — first-pass QA gate (brief mode) or per-iteration QA findings (QA mode).

QA mode (post-render) additionally produces per iteration:

14. outputs/qa/fix_prompt.md — downstream-skill-actionable fix instructions.
15. outputs/qa/qa_iteration.json — round number, status (iterate / pass / needs-human), unresolved findings, history.

Style-gallery mode (--style-gallery, pre-outline gate) instead produces and stops:

16. HTML routes: style_gallery.html plus ≥4 cover entries. PPT Master: no fake gallery HTML; style selection stays in its native Confirm UI.
17. style_gallery_plan.json — cover candidates for HTML or mode: downstream-confirm-ui for PPT Master.
18. commands/style-gallery/<id>.md — cover command for HTML, or ppt-master-confirm-ui.md for the native gate.

Recommended OPC workflow (v0.6.4)

O — Outline + Per-Page Media Direction
  Humanize PPT: raw material → AST outline + per-page media decision
  (deck_brief.md, ast_outline.md, slide_plan.json, speaker_intent.md,
   asset_manifest.md, video_slots.json, style_brief.md)

P — Native Renderer Invocation (100% downstream)
  zh  → guizang-ppt-skill        (Style A or B, native; recommended)
  en  → frontend-slides / beautiful-html-templates (native; recommended)
  pptx → ppt-master (native DrawingML; explicit --renderer ppt-master)
  other HTML-PPT skills → hot-pluggable, same brief contract
  Humanize emits the production prompt and stops. The downstream
  skill renders the deck. Humanize does NOT copy templates, does
  NOT inject SLIDES_HERE / [必填] replacements, does NOT add
  postMessage bridges to the rendered HTML.

Q — Presentation Checkup (演讲体检) on the rendered artifact
  Humanize --qa-from <rendered.html|native.pptx> reads the output of P,
  compares pages against the outline, scans for failure modes
  (references/qa-failure-modes.md), writes qa_report.md and
  fix_prompt.md, tracks iteration in qa_iteration.json.
  Cap: 3 rounds. After cap with remaining findings, status
  flips to needs-human.

C — Complete / Control
  Downstream skill native speaker notes + presenter shell + deploy
  (Humanize does not own these in v0.6.4 — the brief tells the
  next agent to produce them in the downstream skill's own format)

Rules