返回 ppt-master
quick-generate.md
根目录 / skills / ppt-master / workflows / profiles / quick-generate.md
1 ---
2 description: One-pass Generate profile for agent-decided preparation, direct SVG authoring, and final PPTX delivery without durable planning or confirmation artifacts.
3 ---
4
5 # Quick Generate Profile
6
7 > Generate-PPTX profile, not a top-level route. The current main agent completes
8 > one uninterrupted run without a separate Strategist/confirmation handoff or a
9 > resumable design record. This removes interaction and traceability, not the
10 > facts, resources, or authoring capabilities needed to build the final deck.
11
12 **Trigger**: the user explicitly requests quick/fast generation, asks to skip
13 strategy/confirmation, or directs the agent to proceed to SVG and export.
14 Page count alone never activates or blocks this profile.
15
16 ---
17
18 ## 1. Profile Boundary
19
20 | Concern | Quick Generate contract |
21 |---|---|
22 | Authority | Follow every explicit user requirement as stated; decide every unspecified choice directly without asking |
23 | Interaction | The current main agent decides content, design, resources, and implementation without Strategist, Confirm UI, or approval stops |
24 | Execution memory | Keep routine page, visual, and resource decisions only in the current active context; losing that context restarts Quick instead of reconstructing a plan from project files |
25 | Inputs | Any supported Generate input; convert/import sources and run bounded factual research when the input requires them |
26 | Templates | Directly validate and install at most one exact workspace root per kind supplied for this run; when none are supplied, use free design without catalog selection or Confirm UI |
27 | Resources | Prepare every project-local image, icon, formula, and required provenance/manifest artifact before the referencing SVG is authored |
28 | Planning artifacts | Do not author a root project `design_spec.md`, `spec_lock.md`, confirmation payloads, or any substitute planning artifact; an installed `templates/design_spec.md` remains template input |
29 | Traceability | Operational resource manifests, checker reports, postflight, and bounded Python command/outcome audit entries may remain, but they do not record the AI's design reasoning or form a resumable generation history |
30 | Delivery | Hand-author the resolved SVG roster, run one lockless final checker, skip `finalize_svg.py`, and export the final native PPTX through `--quick-generate` |
31
32 **Artifact ownership**: follow
33 [`artifact-ownership.md`](../../references/artifact-ownership.md) for source,
34 fact, author, derived, and regeneration boundaries. Quick changes the planning
35 handoff, not those artifact roles.
36
37 **Hard rule — speed removes interaction and durable planning, not capability**:
38 all ordinary source, research, visual-carrier, resource-preparation, analysis,
39 authoring, and export capabilities remain available when they serve the deck.
40 This is capability availability, not a requirement to use every carrier.
41
42 Explicit user facts, wording, choices, exclusions, and permission boundaries
43 still win. For every unspecified routine choice, decide directly and continue;
44 do not ask the user to approve a strategy or implementation detail.
45
46 After entry, continue through selected work, the final checker, and export.
47 Pause only for user interruption or an unresolved hard prerequisite.
48
49 **Default — optional production behavior (may override when useful)**: Speaker
50 notes, custom object animations, and narration start off. The current agent may
51 enable any ordinary capability when the request or deck benefits; use its
52 normal inputs, flags, and prerequisites without asking for approval. Quick
53 never creates or reads a root project Design Spec or lock to enable it.
54
55 **Mandatory — discover motion before deciding whether to load it**: scan this
56 compact gate once; do not load the full execution reference when the defaults
57 already fit.
58
59 | Signal | Action |
60 |---|---|
61 | The same semantic object or scene continues across adjacent pages | Load [`animations.md`](../../references/animations.md) before SVG authoring; prepare both visible endpoints and use its Morph contract |
62 | Page- or object-specific reveal, renewed emphasis, meaningful movement, or same-page removal clarifies the message | Load [`animations.md`](../../references/animations.md) before SVG authoring; preserve the required units/states, then run [`customize-animations`](../stages/customize-animations.md) after the final checker |
63 | One deck-wide entrance policy supplies all required staged reveal | Load [`animations.md`](../../references/animations.md) before export and use an exporter flag such as `-a auto`; do not run the custom stage |
64 | A directional/section boundary benefits from a non-default transition | Load [`animations.md`](../../references/animations.md) before export and select from its §3 playbook |
65 | No earlier signal applies | Keep `fade` transitions and object animation `none`; do not load the motion reference |
66
67 This gate activates capability discovery, not motion coverage. Keep the
68 defaults when no row supplies a concrete communication job. When several
69 signals apply, perform every required action and use the earliest required load
70 point; a before-authoring signal always overrides a before-export-only timing.
71
72 ---
73
74 ## 2. Source and Resource Preparation
75
76 Prepare source facts before initialization:
77
78 | Input | Action |
79 |---|---|
80 | Topic or requirements without supporting facts | Run [`topic-research`](../stages/topic-research.md) immediately and retain its Markdown supplement plus fact-provenance JSON for import |
81 | PDF / DOCX / Office document / XLSX / XLSM / PPTX / EPUB / HTML / LaTeX / RST / web URL | Run `python3 ${SKILL_DIR}/scripts/source_to_md.py <file_or_URL_or_dir> [<file_or_URL_or_dir> ...]` |
82 | CSV / TSV | Read directly as a plain-text table source |
83 | Markdown or direct conversation text | Read directly |
84
85 The conversion dispatcher writes standard Markdown plus its conversion profile
86 beside each local source by default. Use `-t <type>` only when detection is
87 ambiguous and `-o` only for a required output path; with several or directory
88 inputs, `-o` names an output directory. A PPTX is converted to Markdown here and
89 receives its project analysis during the import step below.
90
91 After reading every direct and converted source, assess factual sufficiency:
92
93 | Material state | Action |
94 |---|---|
95 | The requested outcome is supported | Continue |
96 | A required externally verifiable claim remains unsupported | Run [`topic-research`](../stages/topic-research.md) for those gaps only |
97 | Closed corpus / source-only / no external enrichment | Stay within the supplied material |
98
99 **Sufficiency test**: research only when the requested outcome would otherwise
100 require inventing, omitting, or leaving unsupported an externally verifiable
101 claim. File presence or length does not establish sufficiency. Research gathers
102 facts only; image acquisition remains part of the resource preparation below.
103
104 Before initialization, resolve exactly one template branch:
105
106 - **Direct template application**: one or more exact current workspace roots
107 were supplied in the request, or Create Template returned an exact validated
108 root in the current conversation. Accept at most one root per declared kind.
109 Before initialization, load
110 [`apply-template-workspace`](../stages/apply-template-workspace.md), normalize
111 each supplied root, read only the matching spec frontmatter needed to resolve
112 its kind/canvas, and run that stage's read-only schema/structured preflight.
113 Do not scan the library, fuzzy-match a name, or open a selector. Explicit user
114 canvas wins; otherwise use the selected structure owner (Layout before Deck)
115 canvas when present, then fall back to `ppt169`.
116 - **Free design**: no exact root was supplied. Continue immediately with the
117 requested canvas or `ppt169`. A bare template name, brand mention, style
118 phrase, or vague request to choose a template is ordinary brief input, not a
119 workspace reference.
120
121 Neither branch creates anything under `confirm_ui/` or executes
122 `confirm_ui/server.py`. Initialize the minimal workspace with:
123
124 ```bash
125 python3 ${SKILL_DIR}/scripts/project_manager.py init <project_name> \
126 --format <format> --quick-generate
127 ```
128
129 It creates `svg_output/` plus the cold
130 `validation/workflow.log` command/outcome audit log, and no root README. After
131 this command, run project-scoped Python tools directly; their shared CLI
132 bootstrap records command envelopes, material tagged outcomes, bounded status
133 samples, and omission counts. A concise manual entry is allowed only for a
134 material stage handoff, rework reason, user-approved exception, or manual
135 recovery choice that has no owning command output; do not record routine page
136 progress, artifact contents, or private reasoning.
137 Never read the log during ordinary Quick execution; open it only for an
138 explicit user-requested run review. Add
139 capability inputs only when triggered; later tools create `exports/` and the
140 default-path `backup/`.
141
142 With file-based sources, import the original inputs, converted outputs, and any
143 research pair together:
144
145 ```bash
146 python3 ${SKILL_DIR}/scripts/project_manager.py import-sources \
147 <project_path> <source_files_or_dirs...> [<converted_outputs...>] \
148 [projects/<research_slug>.md projects/<research_slug>.facts.json]
149 ```
150
151 Only inputs already under the repository's `projects/` tree move into the
152 target project; every external path is copied and remains untouched. Use
153 `--copy` when a projects-local input must also remain in place. When conversion
154 wrote Markdown beside the original source, pass that source path or directory
155 once; when `-o` wrote it elsewhere, pass both locations. Direct supported bitmap
156 inputs are archived under `sources/` and copied collision-safely into `images/`.
157
158 For each imported PPTX, `import-sources` automatically writes
159 `analysis/<stem>.identity.json`, `analysis/<stem>.slide_library.json`, and the
160 multi-deck `analysis/source_profile.json` index. Read that index as source facts
161 and open a per-deck artifact only when the current task needs its additional
162 detail; these facts are recommendations, not replica constraints. Distinct PPTX
163 stems may coexist, and re-importing one stem replaces only that deck's entry.
164
165 Conversion companion manifests may place extracted SVG/EMF/WMF assets into the
166 project resource flow. Preserve EMF/WMF as vector references and never convert
167 them to PNG; browser preview may be blank while native PPTX export remains the
168 source of truth. Standalone SVG/EMF/WMF inputs remain source assets unless such
169 a manifest supplies their display metadata.
170
171 Never scaffold a Design Spec or lock. Use a new path, or verify that an existing
172 path's `svg_output/` is empty; Quick ignores any existing `design_spec.md` or
173 `spec_lock.md`.
174
175 The audit log is an operational tool record only. It does not capture direct
176 SVG authoring, active-context design choices, or private reasoning and cannot be
177 used to resume or reconstruct a Quick run.
178
179 For the direct-template branch, continue with
180 [`apply-template-workspace`](../stages/apply-template-workspace.md) after
181 initialization against only the preflighted roots. The user's request is the
182 selection authority; there is no template confirmation receipt or handoff. The
183 stage installs and fuses the workspaces into `<project_path>/templates/` plus
184 the project-local asset pools. All later reads use that installed state, never
185 the original roots.
186
187 Before writing P01, read the installed template spec once and, for Layout/Deck,
188 inspect the relevant SVG prototypes. Apply Brand identity, Style
189 direction/method, the selected structure owner's useful prototype geometry,
190 and Deck application context directly in the active context under the existing
191 segment precedence. Follow explicit instructions about literal or visual-only
192 use; otherwise decide which prototypes to use, skip, repeat, reorder, or adapt
193 while authoring. Persist no separate template-application artifact. If no
194 template was installed, make the same design choices freely.
195
196 **One-pass decision boundary**: resolve only what is needed to author this deck
197 in the current context. Do not print a strategy summary, create a planning
198 checkpoint, or persist a page/resource plan.
199
200 Before writing P01, resolve in active context:
201
202 - the exact slide roster and one compact core message for every page, used to choose its composition and hierarchy;
203 - the canvas, visual direction, palette, wording, and one concrete typography plan using installed font families, with stable size anchors for title, body, annotation, and every other recurring role the roster uses; explicit user, template, or resolved-style requirements may call for a deliberate exception;
204 - an ordinary body-content frame and a density judgment for every page, adapted to the canvas and any user / template / style geometry; use `anchor`, `dense`, `breathing`, or an equivalent active-context distinction instead of one uniform fill level;
205 - for each page not bound to literal supplied geometry, a primary visual zone and page-scale composition direction tied to its core message; use cards or equal grids when the content relationship calls for them, not as the automatic page grammar;
206 - when useful, one transient deck-level visual motif with an identity or
207 communication job, a recognizable invariant, and deliberate variation across
208 applicable page roles; omit it when restraint serves the deck better;
209 - the resource decisions needed for immediate preparation. Required operational
210 image/formula manifests may carry filenames, page relationship, status, and
211 generation/crop/focal cues, but do not create a general resource roster or an
212 icon-to-page assignment;
213 - the implementation path for each resource. An explicit user path wins;
214 otherwise choose the registered automatic/default path without another
215 interaction.
216
217 **Mandatory — capability scan, not a coverage quota**: for every page, consider
218 the complete carrier menu once and choose only the forms that communicate its
219 content best. A decision to use none of a carrier is valid; skipping the scan
220 because Quick is expected to be faster is not.
221
222 | Communication job | Available carrier |
223 |---|---|
224 | Real subject, place, product, evidence, atmosphere, or scene benefits from visual grounding | Supplied/extracted, web, AI, or sliced image |
225 | A compact semantic cue clarifies a category, process, KPI, state, navigation item, or real brand | Prepared project-local icon |
226 | Editable geometry can express a relationship, flow, emphasis, callout, symbol, or diagram | Basic SVG primitive, exact Office preset, Boolean result, then necessary freeform |
227 | Values encode comparison, trend, distribution, composition, relationship, or a text grid | Data chart or table, with optional native Chart/Table metadata when its object model is useful |
228 | Mathematical notation is clearer as typeset math than ordinary text | Rendered formula asset |
229 | Typography, spacing, and simple geometry already carry the message | Use no additional visual carrier |
230
231 Prepare only the resource paths needed by the decided pages:
232
233 | Resource | Required preparation |
234 |---|---|
235 | Supplied/extracted image | Copy the selected file into `images/`; preserve its factual/provenance context and use the measured file rather than an invented substitute |
236 | Bundled/custom icon | Follow the [icon library contract](../../templates/icons/README.md), choose one coherent primary library, sync a useful project pool covering recurring semantics and likely page-local needs without assigning icons to pages, and choose from that prepared pool during SVG authoring |
237 | Formula | Follow the [`latex_render.py` contract](../../scripts/docs/image.md), write `images/formula_manifest.json`, run the renderer, and keep the rendered PNG under `images/` |
238 | AI image | Follow `image-base.md` + `image-generator.md`; keep `image_prompts.json` and its human-readable sidecar |
239 | Web image | Follow `image-base.md` + `image-searcher.md`; keep query/status data and `image_sources.json`, including any required on-slide attribution |
240 | Illustration slice | Generate or obtain the parent sheet, run `slice_images.py`, and place only the resulting element files |
241 | Data chart/table | Keep source values and the chosen page treatment in active context; load the chart/table authorities in §3 before drawing and write native replacement metadata only when selected |
242
243 **Image inspection boundary**: acquisition-time suitability review follows the
244 owning AI/web/slice reference. Once resources reach terminal status, SVG
245 authoring follows `executor-image.md`'s narrow placement inspection: inspect only
246 one specifically ambiguous `Existing`/`Sourced` asset and never routinely reopen
247 `Generated` outputs.
248
249 After image resources change, run `analyze_images.py` so
250 `analysis/image_analysis.csv` reflects the files that SVG authoring will use.
251 Operational manifests and provenance are resource truth, not a hidden design
252 strategy.
253
254 Every required resource must reach a usable terminal state before the
255 referencing page is authored. A required `Needs-Manual` resource blocks Quick
256 delivery even when an unverified candidate file exists. After a manual supply
257 or replacement, validate the file/provenance and reconcile the row to
258 `Generated`, `Sourced`, or `Rendered`; do not use file presence as a bypass or
259 silently replace it with unrelated material.
260
261 ---
262
263 ## 3. Direct SVG Authoring
264
265 Always read the following fixed authoring references directly in one batch; do
266 not route among them one file at a time:
267 [`shared-standards-core.md`](../../references/shared-standards-core.md),
268 [`svg-effects.md`](../../references/svg-effects.md),
269 [`native-shape-authoring.md`](../../references/native-shape-authoring.md),
270 [`semantic-svg.md`](../../references/semantic-svg.md),
271 [`modes/_index.md`](../../references/modes/_index.md), and
272 [`visual-styles/_index.md`](../../references/visual-styles/_index.md). Resolve
273 one narrative mode and one visual style from explicit user/template requirements
274 or the current content, keep that choice only in active context, and read every
275 exact preset source actually used once. A genuinely novel custom direction
276 follows its resolved behavior without inventing a nearby preset.
277
278 Do not load `executor-base.md`: it owns Default's persisted-plan handoff,
279 first-page gate, and completion routing. Excluding that file is not a capability
280 exclusion; Quick loads the shared and conditional execution authorities here
281 directly. For any image/formula, always read
282 [`executor-image.md`](../../references/executor-image.md),
283 [`image-layout-spec.md`](../../references/image-layout-spec.md),
284 [`image-layout-patterns.md`](../../references/image-layout-patterns.md), and
285 [`svg-image-embedding.md`](../../references/svg-image-embedding.md); add
286 [`executor-web-image.md`](../../references/executor-web-image.md) for a sourced
287 web image. Load [`canvas-formats.md`](../../references/canvas-formats.md) only
288 for a non-default canvas.
289
290 | Deterministic trigger | Additional authority |
291 |---|---|
292 | Any data chart or text-grid table, including mini/inset charts and sparklines | [`executor-chart.md`](../../references/executor-chart.md); use bounded [`chart_recall.py`](../../scripts/docs/chart-recall.md) only when a reusable visualization reference would help |
293 | Preset pattern or selected PowerPoint-native Chart/Table replacement | [`native-data-interface.md`](../../references/native-data-interface.md) before drawing the object |
294 | Any data-driven chart geometry | [`verify-charts.md`](../stages/verify-charts.md) after the complete roster and before the one final checker |
295
296 Keep the core's shared visual-quality / leading defaults and `svg-effects.md` §6.1 Visual Job Router active while authoring. Explicit user/template requirements and the resolved style override compatible aesthetic defaults, never technical Required / Forbidden boundaries.
297
298 **Per-page execution anchors**: apply the transient core-message, typography-role, body-frame, density, and composition anchors resolved in §2 while authoring; they guide the current run without creating a persisted planning artifact.
299
300 Use one zero-padded filename width sized for the resolved roster, such as
301 `01_cover.svg` through `12_end.svg` or `001_cover.svg` through `120_end.svg`.
302 Never reuse pages from another run: the exporter publishes every SVG discovered
303 under `svg_output/`.
304
305 **Canvas**: use the canvas resolved in §2: explicit user choice, otherwise the
306 selected Layout/Deck structure-owner canvas, otherwise `ppt169` with
307 `viewBox="0 0 1280 720"`. For another registered format, load
308 [`canvas-formats.md`](../../references/canvas-formats.md) and use its exact
309 viewBox. Template canvas is a default, not a compatibility gate; an explicit
310 user canvas may adapt the installed visual system. The first SVG establishes
311 the export canvas; every remaining page must match it exactly.
312
313 **Structure**: author flat, Slide-local SVG only, including when a Layout or
314 Deck workspace is installed. In that branch, visibly realize the resolved
315 template rules and prototype geometry in the complete pages; do not fall back to
316 free design or merely explain how the template could be used. Include the
317 complete visible page and all resource references in each SVG; set one root
318 `data-pptx-page-role` from `cover`, `toc`, `section`, `content`, or `ending`,
319 and omit Master/Layout/layer/placeholder metadata. A request that specifically
320 requires reusable native Master/Layout/placeholder output is incompatible with
321 the lockless Quick exporter and must use the default lock-backed profile.
322
323 **Typography**: name an installed concrete font family in the SVG; do not depend
324 on a lock or generated font asset.
325
326 **Generation pacing**: the current main agent hand-writes the SVG roster in
327 order. Use P01 as the visual anchor and continue directly through the remaining
328 pages without a first-page checker or confirmation stop. When a motif was
329 resolved, reuse it selectively and vary scale, crop, density, position, or
330 content interaction instead of cloning one ornament. Keep this choice only in
331 active context; create no planning artifact or approval stop. After every page
332 exists, run the one final checker below. Apply other supporting tools and
333 stages only when their capability is actually needed.
334
335 This is not a resume protocol. If the active context is lost before delivery,
336 start a clean Quick run rather than inferring an unfinished plan from the files
337 already present.
338
339 ---
340
341 ## 4. Export
342
343 After every page and required referenced resource exists, run the Quick branch
344 of [`verify-charts`](../stages/verify-charts.md) when any data-driven chart was
345 authored. Complete all coordinate repairs first; then run the one lockless final
346 SVG check:
347
348 ```bash
349 python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> \
350 --quick-generate --stage final --json
351 ```
352
353 Fix every blocking error and rerun the same command. Then export:
354
355 ```bash
356 python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path> --quick-generate
357 ```
358
359 `--quick-generate` reads `svg_output/` as the page source and resolves the
360 project-local assets referenced by those SVGs. It infers one consistent canvas,
361 uses a lockless flat PowerPoint package, and does not force-disable ordinary
362 export options. Notes, custom object animation, and narration remain off unless
363 selected by the agent. Do not run `finalize_svg.py`.
364
365 The exporter requires a passing `final` report whose SVG fingerprint matches
366 the current `svg_output/`; missing, blocking, non-final, or stale reports stop
367 before PPTX creation. The default output path retains ordinary backup and
368 postflight behavior. An explicit `-o <path>.pptx` keeps the ordinary no-backup
369 behavior. On failure, repair the owning SVG, resource, or optional capability
370 input, rerun the final checker, then export again; do not create a Design Spec
371 or lock.
372
373 ```markdown
374 ## ✅ Quick Generate Complete
375
376 - [x] All required source/resource preparation is complete
377 - [x] One mode and visual style were resolved, and every catalog source actually used was read
378 - [x] Every page considered the complete visual-carrier menu without a coverage quota
379 - [x] Resolved SVG pages and their project-local references exist
380 - [x] Every triggered capability-specific preparation and pre-checker verification completed
381 - [x] The lockless final SVG quality report passes and matches the current SVGs
382 - [x] One native PPTX exists under `exports/` or the explicit output path
383 - [x] No Strategist, confirmation, root project Design Spec, or lock artifact was created
384 - [ ] **Next**: Report the PPTX path
385 ```
386
386 lines MARKDOWN