Presentation Report Preflight

Presentation Report Preflight

Objective

Create a Presentation Strategy Brief before any downstream slide-generation skill starts visual design, HTML implementation, animation, or export work. Make the presentation effective as a report, pitch, talk, defense, class, or decision artifact—not merely attractive.

This is an independent upstream skill. It does not generate the final HTML deck. It prepares direction, timing strategy, story, structure, page-level content blueprints, evidence, slide titles, speaker notes, Q&A risks, visual intent, constraints, and a handoff contract that downstream skills can execute.

Core rules

1. Infer first: extract scenario, audience, objective, duration, source material, language, assets, and likely downstream target from the user's prompt and attached/source files before asking.
2. Confirm direction before brief: before building the slide title chain or full brief, show an inferred Direction Snapshot plus Timing Brief and ask for confirmation. Skip only when the user says “先出片”, “别问”, “直接给”, “just make it”, or clearly asks for immediate full output; in that case state the assumptions and continue.
3. Ask lightly: ask at most one batched clarification message only for missing items that would materially change the brief. Direction confirmation is not interrogation: it confirms the inferred reporting direction and timing, not a blank questionnaire.
4. Scene before style: decide reporting scenario, audience, desired action, success criteria, and timing strategy before discussing templates or layouts.
5. Story before slides: choose a narrative framework before planning pages. Treat the framework and title chain as negotiable drafts.
6. Time before detail: the timing plan determines depth, page count, section allocation, Q&A reserve, and which pages to cut if time is short.
7. Content before layout: for full briefs, every slide must include a page-level content_spec that defines the message, on-slide copy, visual blueprint, data refs, asset refs, narration, and constraints before downstream skills choose layout, animation, or implementation. Lite briefs use compact content_spec only where it prevents ambiguity.
8. Claims before topics: every slide title must be a conclusion-style claim, not a category label.
9. Evidence before decoration: every metric needs a unit, source, and comparison baseline. Do not invent facts, metrics, sources, customer names, case details, or ROI numbers.
10. One job per page: each slide must have one persuasion/teaching/decision task. Split overloaded pages.
11. Hook and close are mandatory: the first 30 seconds need a hook; the ending needs a CTA, decision request, or memorable takeaway.
12. Speaker notes are part of the deliverable unless the user opts out.
13. The YAML Universal Handoff Contract is the single source of truth. The summary, timing brief, and title-chain table are human-readable projections of it. But the human-readable layer is the primary interface the user reviews — never dump the full YAML at the user for sign-off before they have confirmed the direction and, for full-tier briefs, the title chain.
14. Always output the universal contract. Add an adapter appendix only when a downstream skill is named and resolved at runtime, and build it by reading that downstream skill's current instructions at runtime. The downstream names in this skill are examples only — never assume one exists, never hardcode private layout IDs, preset names, CSS classes, or DOM assumptions. Record what was requested vs. resolved in adapter_resolution.
15. Scale depth to stakes: the size of the brief must match the weight of the talk. Do not apply the full heavy structure to a low-stakes deck. Pick a brief_tier (lite/full) and produce only what that tier needs — over-producing a 5-minute standup with a full evidence/speaker/Q&A contract is the same failure mode as over-interrogating the user.
16. Provenance is explicit, not implied: every evidence item and metric carries a source_status of verified | user_reported | assumed | to_verify. You cannot verify truth, but you must always state the status. Never silently promote a user_reported or assumed number into something that looks verified. Any assumed / to_verify item must surface in the weakest-link self-check and in that page's footnotes.
17. Choose a run mode before the gates: detect run_mode (interactive | autonomous) in Phase 0. interactive keeps the confirmation gates; autonomous replaces every gate with "state assumptions, continue, record in open_questions" and never blocks. Decide by, in order: explicit user instruction → execution context (headless / called by another skill or workflow / no chance to reply) → speed keywords as a last-resort fallback.
18. Density is per-page, orthogonal to tier: each slide carries spec_density (full | compact). Core pages (hook / proof / case / cta, and any page with a key number or required asset) get full; routine pages get compact. For decks over ~20 slides, default to this hybrid even within brief_tier: full so the contract does not explode.
19. Decouple language from structure: contract YAML keys stay in English (machine-stable); the human-readable layer follows output_language. The Chinese section labels in this skill's templates are illustrative defaults for Chinese reporting — translate them when output_language differs.
20. Declare what you read: list the references actually consulted in references_consulted so reference-skipping is visible.

Reference routing

Load only the references needed for the current task:

| Need | Read | | --- | --- | | Pick or explain a narrative structure | references/narrative-frameworks.md | | Apply scenario-specific strategy | references/scenario-playbooks.md | | Plan metrics, comparisons, charts, or KPI pages | references/data-viz-guide.md | | Build page-level content blueprints, information graphics, image slots, on-slide copy, or downstream-ready page details | references/content-spec-guide.md | | Draft speaker notes, timing, Q&A, or data口径 | references/speaker-notes-template.md | | Final self-check and repair guidance | references/presentation-checklist.md | | Resolve / adapt to a named downstream skill | references/downstream-adapter-protocol.md | | Validate the handoff contract structure | references/handoff-contract.schema.json | | Need a complete output model | references/example-brief.md |

Workflow

Phase 0 — Detect input, run mode, handoff mode, downstream target, language

Classify the task:

• new deck from a topic, notes, outline, or raw idea;
• deck from document, research, PDF, data, transcript, or source report;
• rewrite/upgrade an old PPT/PDF/HTML deck;
• strengthen story/logic before a downstream deck skill executes;
• strategy brief only.

Detect run_mode (see core rule 17):

• interactive — there is a real user who can answer; keep the Phase 3.5 and 4.5 gates.
• autonomous — headless run, invoked by another skill/workflow, or the user clearly wants no back-and-forth; skip gates, state assumptions inline, record unknowns in open_questions.
• Decide by priority: explicit instruction → execution context → speed keywords (“先出片”, “别问”, “直接给”, “just make it”) as the last-resort fallback only.

Detect output_language from the user's prompt and source material (default: the language the user is writing in). Contract YAML keys stay English; the human-readable layer and on-slide copy follow output_language.

Select handoff mode:

• universal_only when no downstream skill is specified, the target is unknown or cannot be resolved at runtime, or the user wants a portable brief;
• universal_plus_adapter when the user names one or more downstream skills and they resolve at runtime (see Phase 7 and references/downstream-adapter-protocol.md).

Recognize downstream targets from the user's words. The names frontend-slides-editable, guizang-ppt-skill, huashu-design, “HTML PPT skill” are examples — always confirm the named skill actually exists in the current environment before promising an adapter.

Select brief tier:

• lite when the deck is low-stakes or short: internal weekly sync/standup, a single training segment, status update, or any talk under ~10 minutes / under ~8 slides.
• full when the deck is high-stakes or longer: sales proposal, investor pitch, product launch, promotion defense, consulting/strategy, annual report, or any talk ~10 minutes or more.
• When ambiguous, default to full, state in one line why this tier was chosen, and tell the user they can switch with one word (e.g. “给我精简版/lite”).

Plan spec_density (see core rule 18): brief_tier sets the overall contract weight; spec_density is decided per slide. Mark core pages (hook / proof / case / cta, or any page carrying a key number or required asset) as full, routine pages as compact. For decks over ~20 slides, apply this hybrid even under brief_tier: full so the contract stays handoff-sized instead of exploding.

Phase 1 — Discovery without interrogation

Infer these fields from provided material first:

• scenario: sales proposal, investor pitch, product launch, annual/quarterly report, promotion defense, retrospective, technical talk, training, consulting delivery, strategy report, internal sync, case study, etc.;
• audience: executives, customers, investors, judges, colleagues, learners, public, technical peers;
• desired action or decision;
• success criteria;
• duration or slide-count target;
• available source material, data, images, logo, brand assets, examples;
• language/locale;
• downstream skill preference and export/editability expectations.

Ask only if a missing field cannot be inferred and would change the story or contract. Batch all questions in one concise message. If speed is requested, continue without asking and mark unknowns in open_questions.

Phase 2 — Scenario playbook

When the scenario is known, read references/scenario-playbooks.md. Use the closest playbook to determine the goal, recommended structure, must-have elements, visual implications, and taboos.

Phase 3 — Narrative framework

When choosing or justifying structure, read references/narrative-frameworks.md. Recommend one primary framework and at most one auxiliary framework.

Default mapping:

• Sales proposal → Problem → Solution → Benefit.
• Investor pitch → Pitch Deck 10 pages or AI project roadshow 6 checks.
• Product launch → Hero's Journey + Sparkline.
• Annual/quarterly report → BARO or six-part review.
• Promotion defense（晋升答辩）→ promotion SOP + STAR/BARO.
• Retrospective → four-step review method.
• Technical talk → Why → What → How → Demo → Limitation.
• Training → What → Why → How → Practice → Check.
• Consulting/strategy → SCQA + Pyramid Principle.
• Internal weekly sync → Status → Blockers → Support.
• Case study → Background → Challenge → Solution → Results or PAST.

Phase 3.5 — Direction and Timing Confirmation Gate

Before generating the slide title chain or full brief, produce a compact Direction Snapshot and Timing Brief, then ask one concise confirmation question. This gate applies in run_mode: interactive for both lite and full tiers. In run_mode: autonomous (or when the user explicitly requests speed / immediate output), do not ask: state the snapshot in one short paragraph, record unknowns in open_questions, and continue to Phase 4.

Direction Snapshot must include:

• scenario;
• audience;
• desired action or decision;
• success criteria;
• brief_tier and why;
• recommended narrative framework and why;
• downstream target, if any;
• key assumptions / open unknowns.

Timing Brief must include:

• total duration estimate;
• talk time vs Q&A reserve;
• slide count target;
• pacing model, such as fast pitch, steady report, workshop/training, demo-heavy, or executive brief;
• section-level time allocation;
• heavy slides likely to need extra time;
• compressed version if time is cut in half;
• overrun risks.

Ask a confirmation question like: “我会按这个方向和时长生成 brief。方向/时长对吗？要改听众、目标、叙事骨架、时长，还是直接继续？”

If the user corrects the direction or timing, revise the snapshot before continuing. If the user confirms or says “继续”, proceed to Phase 4. If speed is requested, state the snapshot in one short paragraph, record unknowns in open_questions, and continue without waiting.

Phase 4 — Build the slide title chain

Create a slide-by-slide title chain with:

• slide number;
• narrative stage;
• conclusion-style title;
• slide job;
• evidence/assets;
• suggested visualization or layout intent;
• speaker-note focus.

Rewrite topic-only titles into claims. The title chain should be readable as a complete summary of the presentation.

Phase 4.5 — Confirmation checkpoint (two-beat delivery)

By default, do not expand the full YAML contract yet. After direction and timing are confirmed, first send only the human-readable layer — the 摘要, Timing Brief, and Slide Title Chain table — and ask one concise question, e.g. “改哪几条标题或换骨架，还是直接展开完整 brief？”. The title chain is the artifact the user most needs to review and reject line by line, so let them steer it before you commit the rest.

Skip this checkpoint and go straight to the full output when run_mode is autonomous, when the user signals speed (“先出片”, “别问”, “直接给”, “just make it”), or when brief_tier is lite (a lite brief is already short enough to deliver in one beat).

Phase 4.7 — Page-level content spec

After the direction/timing and title chain are accepted, read references/content-spec-guide.md before expanding the YAML.

For full briefs, every slide_plan item must include a complete content_spec:

• the page's single primary_message;
• concise on-slide copy blocks;
• a visual_blueprint for the main chart, infographic, screenshot, image, table, diagram, or no-visual page;
• data_refs that point to evidence_plan[].id;
• asset_refs that point to asset_plan.catalog[].id;
• narration timing and talking points;
• constraints, split conditions, and placeholder policy.

For lite briefs, add compact content_spec only when it prevents downstream ambiguity: key metrics, action asks, image/screenshot needs, or pages likely to overflow.

Downstream skills may translate visual_blueprint into their own layouts, presets, or components, but they must preserve primary_message, data values, caveats, required assets, and placeholder policy.

Phase 5 — Data and evidence plan

Read references/data-viz-guide.md when the deck includes metrics, ROI, benchmarks, market sizing, timelines, comparisons, charts, or KPI cards.

For every key claim or metric, define:

• value and unit;
• source;
• source_status: verified | user_reported | assumed | to_verify (see core rule 16);
• comparison baseline;
• recommended chart;
• caveat/risk.

Assign each evidence item a stable id so content_spec.visual_blueprint.primary_visual.data_refs can reference it.

Mark missing sources or baselines as 待补来源 / 待补对比基准; never fill with plausible-looking numbers. Any item whose source_status is assumed or to_verify must also be echoed in that page's footnotes and considered for the weakest-link self-check.

Build asset_plan.catalog with stable asset IDs for every logo, screenshot, photo, chart dataset, source document, video, or icon used by any page. Mark each item as provided, extractable, to_fetch, to_generate, placeholder, or unavailable; include permissions and fallback.

Phase 6 — Speaker notes and Q&A plan

Read references/speaker-notes-template.md when the deck is for live presenting or when notes are requested or implied.

For each slide or high-risk section, specify:

• key talking points;
• timing;
• likely questions;
• answer direction;
• data source/definition if relevant.

Prepare explicit Q&A for high-risk pages: market size, financial forecast, competitor comparison, ROI, indiv

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: archlizheng
• Source: archlizheng/presentation-report-preflight
• License: MIT

Install and usage instructions live in the source repository linked above.