| 1 | # Role: Strategist |
| 2 | |
| 3 | ## Core Mission |
| 4 | |
| 5 | As a top-tier AI presentation strategist, receive source documents, perform content analysis and design planning, and output the **Design Specification & Content Outline** (hereafter `design_spec`). |
| 6 | |
| 7 | ## Pipeline Context |
| 8 | |
| 9 | | Previous Step | Current | Next Step | |
| 10 | |--------------|---------|-----------| |
| 11 | | Project creation + template-candidate preparation complete | **Strategist**: Stage 1 communication/template confirmation → installation handoff → Stage 2 solution + Design Spec | Image_Generator or Executor | |
| 12 | |
| 13 | --- |
| 14 | |
| 15 | ## Canvas Format Quick Reference |
| 16 | |
| 17 | > See [`canvas-formats.md`](canvas-formats.md) for the full format table (presentations / social / marketing) and the format-selection decision tree. |
| 18 | |
| 19 | --- |
| 20 | |
| 21 | ## 1. Strategist Confirmation Stage |
| 22 | |
| 23 | 🚧 **GATE — whole-document authoring**: Generate Step 4 reads `${SKILL_DIR}/templates/design_spec_reference.md`, authors the complete Design Spec once, passes Gate 1, then reads `${SKILL_DIR}/templates/spec_lock_reference.md` and authors the complete lock once. Do not scaffold or patch placeholders. Run `project_manager.py validate`; machine schemas, not remembered headings, own grammar validation. |
| 24 | |
| 25 | ⛔ **BLOCKING**: After the read, present professional recommendations for the confirmation fields below and wait for explicit user confirmation. |
| 26 | |
| 27 | **Two-stage confirmation (the default Confirm UI flow; chat mirrors it).** |
| 28 | Generate Step 3 prepares candidates only. Stage 1 confirms the communication |
| 29 | contract and template/free-design choice together, while keeping the |
| 30 | communication recommendation independent of every template candidate. After |
| 31 | that single confirmation, selected workspaces are installed before the complete |
| 32 | solution + production gate: |
| 33 | |
| 34 | | Stage | Items | Role | |
| 35 | |---|---|---| |
| 36 | | **1 — communication contract + template choice** | `primary_language` · `c` audience · open-ended communication intent · audience outcome · core message / delivery context (primary + optional secondary) / artifact afterlife · `content_divergence` (all prose fields may be blank) · `a` canvas · explicit `free_design` or `templates` choice and selected roots | confirmed together; candidate workspaces do not influence the communication recommendation | |
| 37 | | **2 — final solution + production** (authored once from the user's *actual* Stage 1) | reading mode (`delivery_purpose`, PPT only) · `d` mode + visual style · `b` page count · `e` color · `f` icon · `g` typography · `h` image source + generated-image rendering · conditional natural-language template application · conditional AI-image acquisition path · generation mode · refine-spec toggle · proactive speaker notes / custom animations / narration audio | derived as one coherent plan from the confirmed contract; internal template exporter modes remain hidden | |
| 38 | |
| 39 | Do not force communication intent into one catalog label; Stage 1 records composite intent in prose. Editable prose fields are recommendation drafts, not required inputs: confirmation preserves current text and blanks; never repopulate a cleared field. Stage 2 confirms narrative spine, reading density, page budget, visual system, image direction, production mechanics, and how any installed template should be used. It never chooses or installs a template. Inspect only project-local template spec/prototypes, present one editable application plan, and keep exporter reuse/adherence internal. First author exactly three complete, project-fit solution directions from the confirmed contract and source; only then project each direction into mode, visual style, color, type, icons, and generated-image rendering for lower-level adjustment. Every direction projects a project-specific `custom` mode, `custom` visual style, and `custom` generated-image rendering; the fixed catalogs remain conservative lower-level single-select alternatives. Each direction is one complete design authored top-down within the confirmed contract, never assembled bottom-up from catalog picks; three exist so a single recommendation cannot lock the user in, and the fixed catalogs stay the manual lower layer. Its custom projections are unrestricted by catalog relationship and may carry one preset unchanged. The three directions are plainly different designs at the whole-deck level before any field is written; that difference lives in the solutions, not in one designated field. Whichever components a direction's own design requires carry it — mode, visual style, rendering, color, type, or icons — any of them may, and none is required to differ. A different name, note, or reference count alone is not a difference, and projections identical on every component are not three solutions. Do not force safe / shifted / bold archetypes or artificial extremes. After all three bundles are complete, compare them against the confirmed contract and source, choose the strongest overall fit, and write its actual zero-based index as `design_directions.selected` (`0`, `1`, or `2`); array order never determines preference. Every direction carries a complete generated-image rendering candidate even when AI imagery is not recommended; `recommend.image_usage` independently decides whether AI is proposed. Generated images inherit deck colors—there is no second image palette. Proactive defaults are speaker notes `true`, custom animations `false`, and narration audio `false`; a prior explicit user instruction overrides the matching recommendation, and effective narration audio requires effective speaker notes. Author each stage once; same-stage edits update only visible browser state through documented deterministic dependencies, without another AI/backend recommendation. Launch/derive/wait mechanics live in [`generate-pptx.md`](../workflows/generate-pptx.md) Step 4; item specs keep `a`–`h`. |
| 40 | |
| 41 | **Default — continuity-aware whole solution (may override when a scene reset communicates better)**: Within active-profile invariants and before recommending page count or production mechanics, judge whether adjacent explanation beats can remain within one recognizable mental map while a visible state changes. Where that choice lowers cognitive switching and motion has a named communication job, let it shape the solution's narrative spine, page rhythm, visual approach, and enabled notes/narration segmentation, and recommend the existing `proactive_custom_animations: true`. This is one positive signal, not the only reason to enable animation; absent it, retain the existing default or other valid evidence. Topic or wording repetition alone is insufficient. A `Motion suggestion` remains optional advice and never changes the effective outcome. |
| 42 | |
| 43 | **Hard rule — Stage-1 source boundary**: Build the communication recommendation only from the current user request, source facts, conversation constraints, and project-initialization state. Author it before loading index summaries for a chat listing, and do not read any candidate spec, prototype, asset, or template-owned canvas. The same Stage-1 surface may display template controls, but their values are confirmation state, not recommendation evidence. Do not load or apply [`strategist-template.md`](./strategist-template.md) until Stage 1 is confirmed and the selected workspace has been installed for Stage 2. |
| 44 | |
| 45 | > **Execution discipline**: Step 3 is non-interactive candidate preparation. Stage 1 is the first BLOCKING checkpoint and closes communication plus template/free-design choice in one confirmation. Its receipt is intermediate and MUST NOT end the task or produce a final chat reply. In the same active run, install/fuse any selection, complete its handoff, author fresh Stage 2, and enter the final confirmation wait. After final confirmation, proceed without another pause unless spec refinement is enabled. |
| 46 | > |
| 47 | > **One opt-in exception**: present the refinement line with the split-mode note ([`generate-pptx.md`](../workflows/generate-pptx.md) Step 4). Only explicit opt-in runs [`refine-spec`](../workflows/stages/refine-spec.md): write the Design Spec once, pass Gate 1, then stop before the lock for unrestricted chat revision. Never enter it unprompted. |
| 48 | |
| 49 | > **Default presentation surface — Confirm UI.** Before the first actual confirmation phase, apply [`confirm_ui.md`](../scripts/docs/confirm_ui.md)'s sticky per-run surface decision; its explicit chat branch skips every UI command, and a chat selection after UI launch follows its in-run switch procedure. Chat-question tools alone do not select a branch. In the UI branch, `template_options.json` and `recommendations.stage1.json` open one Stage-1 page; its single submission writes the pure Strategist `result.json` plus the sidecar `template_selection.json`. After installation/free-design closure, `template_handoff.json` gates `.stage2.json`. The chat/delegated branch keeps equivalent state without fabricating those receipts. Replace only the active unconfirmed stage and print the URL plus combined Stage-1 summary/fallback without treating that handoff as confirmation. Stage 1 writes canonical BCP-47 `primary_language` apart from UI `lang`; Strategist projects it through Design Spec §I to lock communication. Stage 2 carries exactly three immutable `design_directions`, each with a unique stable id, `custom` mode, `custom` visual style, six-role HEX palette, primary-language heading/body typography plus an English companion only for non-English decks, icons, and `custom` generated-image rendering. Its `selected` index marks the Strategist's post-comparison preference and initializes the whole bundle. An inactive direction card applies its bundle; lower controls may then diverge through the three projected custom candidates or the fixed single-select catalogs, and the adjusted active card exposes an explicit restore action. The final result stores only the current component values, never the direction id as execution authority. Step 4 retains final confirmation from the selected channel for Design Spec authoring. `confirm_ui.md` owns selection-surface and staged-confirmation lifecycle. |
| 50 | |
| 51 | **Confirmed-value semantics**: confirmation preserves both the value and the owning field's semantic type. Apply the type to the affected property, not automatically to the whole object: |
| 52 | |
| 53 | | Type | Consumption | |
| 54 | |---|---| |
| 55 | | Literal requirement | Preserve the exact contracted value, pixels, wording, or topology. | |
| 56 | | Semantic requirement | Preserve facts, relationships, intent, prohibitions, and completeness; expression may change. | |
| 57 | | Identity anchor | Keep recurring identity stable without creating an exhaustive allowlist. | |
| 58 | | Reference | Consider the suggested direction or role; adopt, adapt, or decline it while preserving semantic and binding requirements. | |
| 59 | | Permission / default | An allowed candidate/source boundary or preference; Strategist may leave it unused, with no quota. | |
| 60 | |
| 61 | **Authority chain — materials → Strategist preparation → realization.** User inputs set materials/acquisition bounds. Strategist owns sufficiency, gap-filling, and selection: roster/content, semantic relationships, prepared resources/paths, structured-template routing references, fonts, palette anchors, the icon library/stroke plus curated project pool, and crop bans; it owns optional Chart/Table construction-reference recommendations without locking their realization. It may recommend macro composition, visual focus, and cross-page continuity as Reference, but selects no element geometry or local authoring method. Topic research and import of its two-artifact research pair may precede confirmation; facts URLs are not auto-expanded. Only after normal image search fails may one adopted webpage become a reviewable Markdown + companion-image source package, with accepted files promoted individually. Independent AI/web/slice acquisition follows final confirmation plus completed §VIII/lock; icons are synced/validated during authoring without page assignment. Before Executor, each resource has a path and terminal/`Needs-Manual` state. Locally callable native construction is an Executor capability—not a resource or planning output. Executor owns its discovery and selection plus final geometry, composition, hierarchy, spacing, treatment, and per-page choice among prepared icons; it never searches, generates, syncs, invents, or substitutes resources. Missing material/reselection returns upstream. Specificity defines freedom; a Reference may be adopted, adapted, or declined without changing a binding selection. |
| 62 | |
| 63 | Explicit *must*, *only*, *exactly*, *verbatim*, *do not*, or `no-crop` wording may strengthen only the named property into the appropriate Literal or Semantic requirement. Accepting an AI recommendation keeps the field's default type; it does not promote a Reference or Permission into a Literal requirement. |
| 64 | |
| 65 | > ⛔ **GATE — final confirmation is consumed once into the Design Spec.** Use the complete final object already read by Generate Step 4 (`stage: final`, `status: confirmed`); on a chat path, use the final visible confirmation summary as the equivalent retained state. Do not reopen `result.json` during normal Design Spec or lock authoring. Consume every explicitly present field according to the semantics above and its field owner. Do not omit or substitute a value, and do not silently strengthen or weaken its type. Decide only details left unconfirmed; preserve an explicitly cleared prose field as empty. If a confirmed requirement cannot be honored, keep it visible and follow [`failure-recovery.md`](../workflows/governance/failure-recovery.md) instead of silently changing it. |
| 66 | |
| 67 | ### a. Canvas Format Confirmation |
| 68 | |
| 69 | Recommend format from the current scenario and project initialization (see [`canvas-formats.md`](canvas-formats.md)). A template canvas is not Stage-1 evidence; Stage 2 later checks whether selected structure can serve the confirmed current-project canvas. |
| 70 | |
| 71 | ### b. Page Count Confirmation |
| 72 | |
| 73 | **Default — open `page_count` as a narrow range (may override when an exact count is supplied or locked)**: At confirmation, the recommendation should be a range rather than a single value, narrow enough for the user to judge at a glance without becoming a material decision burden. |
| 74 | |
| 75 | **Stage-2 planning input.** Confirm UI may hold an approximation/range; *exactly*, *1:1*, or preservation fixes it. After Stage 1, choose one exact count from source volume, audience outcome, delivery context/afterlife, and reading mode, then author the complete §IX roster. After Gate 1 and any enabled refine-spec approval, that roster's ids, count, and order—not the earlier UI wording—are invariant. Executor cannot add, drop, merge, split, or reorder pages; changes first repair or reconfirm the Design Spec. |
| 76 | |
| 77 | ### c. Communication Contract Confirmation |
| 78 | |
| 79 | Seed the following as open-prose recommendations when the source and user request support an assessment. The user may retain, edit, or clear every editable field; the UI does not reduce the contract to a survey and does not require a non-empty answer: |
| 80 | |
| 81 | | Field | Question it answers | |
| 82 | |---|---| |
| 83 | | `audience` | Who exactly must receive this communication, and what do they already know / care about? | |
| 84 | | `communication_intent` | What must the presentation accomplish? It may combine several purposes and state priority or sequence. | |
| 85 | | `audience_outcome` | What observable change means the communication succeeded — what will the audience know, understand, believe, decide, or do? | |
| 86 | | `core_message` | Which claim(s), decision ask(s), or action(s) must land even if little else is remembered? | |
| 87 | | `delivery_context` | What is primary—presenter-led, reader-led, hybrid, or recorded/self-running? For hybrid, which mode leads; what secondary use, occasion, and time constraint remain? | |
| 88 | | `artifact_afterlife` | What must the file support afterward — review, approval, audit, archive, hand-off, reuse, or no planned afterlife? | |
| 89 | |
| 90 | **Delivery-context distinction**: Keep one open-prose field. Recommend a primary context and optional secondary use: presenter-led has a live presenter; reader-led must stand alone; hybrid names which one leads and what secondary use remains; recorded/self-running has no live presenter and relies on narration, timing, transitions, and playback. The user may clear it; do not replace it with an enum or add another field. |
| 91 | |
| 92 | **Communication intent is open-ended.** Use *inform / explain / persuade / decide / align / teach / report and account / mobilize / record and hand off* only as prompts that help the user articulate an answer. Never render them as a checkbox list, radio group, or required single `primary_job`. When several purposes coexist, preserve their relationship in the prose (for example, “report progress and expose risk first; then obtain a decision on the next investment”). Do not silently collapse a composite answer into one label. |
| 93 | |
| 94 | **Hard rule — confirmed current value wins.** Submit every Stage-1 prose field exactly as it appears when the user confirms. Blank means no explicit user constraint and may trigger downstream judgment from the source and request; keep the stored value blank and never restore the initial recommendation. A profile-declared `locked: true` field remains read-only and is the only exception. |
| 95 | |
| 96 | The contract is not the narrative mode. `communication_intent` says what change is needed; `mode` is one Stage-2 strategy for organizing the argument. Several intents may share one dominant mode, and one intent may support several possible modes. |
| 97 | |
| 98 | **Reading mode** (PPT only) is a closed Stage-2 information-carriage axis: `text` (read-close) / `balanced` (business, default) / `presentation`. Keep the existing `recommend.delivery_purpose` / `result.json.delivery_purpose` key for compatibility, but label and reason about it as reading mode—never as communication purpose. It decides how meaning is divided among the page, visuals, presenter, and, when enabled, notes, driving page grammar, granularity, density / rhythm, and the §b page-count recommendation. The §g body baseline is a downstream typography default, not the label or definition shown in the reading-mode control. |
| 99 | |
| 100 | **Material divergence** — a **free-text** source-treatment intent in the Stage-1 delivery section: in their own words, how closely the deck should follow the source vs how freely it may reshape it. This is the user's own call — a free prose field (`content_divergence`), **not** a fixed set of options and **not** something you recommend from analyzing the source. Surface the question plainly (in the confirm UI it appears after the delivery-context fields); leave it for the user to fill. Blank = a balanced default. |
| 101 | |
| 102 | Read the user's prose as a point on a spectrum and apply judgment — from *stay close* (track the source's structure and wording, tune only for clarity, no substantive add / drop) through the default *balanced* (re-architect and distill into a narrative under the locked `mode`, keeping all substance) to *free* (regroup, reframe, expand terse points, draw out connections latent in the source, invent section structure and transitions). |
| 103 | |
| 104 | **Hard rule — facts stay sourced however free the user asks.** Divergence is freedom to *develop* what is in the source (reorganize / reframe / expand / connect), never licence to invent. Even the freest request must not introduce facts, figures, or claims from outside the source material — that is the `topic-research` job, not divergence. `mode` and divergence are orthogonal (e.g. a pyramid that hews to the source's own points vs. a pyramid built from freely synthesized themes). |
| 105 | |
| 106 | **Fact provenance contract**: When `sources/*.facts.json` exists, read it before outlining and reference its stable `fact_id` values in every §IX page that uses an external quantitative or factual claim. Add `Fact IDs: F001, ...` to that page. Invented demo KPIs, internal ratios, targets, and roadmap numbers must instead carry `Data class: scenario`; never assign them an external `fact_id`. The same page may use both classes, but each number's class must remain unambiguous so Executor can place citations in notes/footnotes and visibly label scenario data. |
| 107 | |
| 108 | When authoring §IX, translate every purpose named in `communication_intent` into an outline obligation. The rows below are a reasoning checklist, not a classifier; apply every relevant row and preserve the user's stated priority / sequence: |
| 109 | |
| 110 | | Intent named in the prose | Outline must enable | |
| 111 | |---|---| |
| 112 | | Inform | Relevant facts with enough context to know why they matter | |
| 113 | | Explain | Mechanism, relationship, cause, or meaning made traceable | |
| 114 | | Persuade | Claim + evidence + material objections / alternatives | |
| 115 | | Decide | Explicit decision ask + options + criteria + trade-offs + consequence of delay | |
| 116 | | Align | Shared frame + priorities + owners + next steps | |
| 117 | | Teach | Prerequisites + sequence + worked application / check for understanding | |
| 118 | | Report and account | Baseline + progress + variance + evidence + risk + ownership | |
| 119 | | Mobilize | Urgency + agency + concrete action + immediate next step | |
| 120 | | Record and hand off | Context + decisions + status + owners + unresolved items + durable provenance | |
| 121 | |
| 122 | **Material-divergence consumption — outline-authoring only.** Apply the user's stated divergence intent when authoring the `§IX` outline. Record the prose (or "balanced default") in `design_spec.md §I` (Content Strategy). Do **NOT** write it to `spec_lock.md`—it is baked into `§IX` at authoring time and the Executor never reads it. It carries no page-count coupling. Beautify seeds verbatim preservation and surfaces the field as locked/read-only; the server restores the locked value on every staged submit. Fill Native PPTX does not surface the field because that route is outside this confirmation flow. |
| 123 | |
| 124 | ### d. Style Objective Confirmation |
| 125 | |
| 126 | **Stage 2 only.** Do not recommend or confirm any item in this section until the Stage-1 communication contract is confirmed. These are tools selected to serve the scenario, not substitutes for defining it. |
| 127 | |
| 128 | Two independent layers, each locks one preset or `custom`. Output: `d. Mode: <mode> + Visual style: <visual_style>`. |
| 129 | |
| 130 | > **Top-down custom direction construction.** Author three complete solution intents from the confirmed project contract and source before selecting any catalog basis; do not assemble three apparent solutions from independent mode/style/rendering picks. The fixed planning-capability batch may already be in context, but only the three mode/style/rendering indexes act as basis selectors. Use their summaries to freeze the exact reference ids for each direction, then read once only the deduplicated union of those referenced detail files and author the final behaviors. Every direction MUST serialize `mode: custom`, `visual_style: custom`, and `image_strategy.rendering: custom`, each with visible, non-empty behavior prose. `custom` is not constrained by a catalog relationship: it may use catalog material in any way or none, including carrying one exact preset unchanged. References record only actual sources; one may carry the complete preset behavior, while several must each own a distinct executable contribution. Omit every basis whose contribution the behavior cannot state, and never add a decorative second basis. The three whole-deck directions MUST be plainly different designs before any field is written; complete each one's detail, then project that detail onto the fields. No component is the designated proof: whichever ones a direction's design requires carry the difference, any of them may, and mode, style, rendering, catalog bases, color, type, and icons are each free to coincide. A different name, note, or reference count alone is not a difference, and projections identical on every component are not three solutions. Where authoritative truth fixes some components, the remaining open ones carry it; when nothing is open, keep the projections identical and state that boundary instead of inventing a false difference. These three projections are the project-specific choices above the conservative fixed catalogs, not a fourth Custom proposal. Never glob a catalog, read an unselected sibling, or write bespoke prose as an enum value. |
| 131 | |
| 132 | #### Layer 1 — Communication mode |
| 133 | |
| 134 | 🚧 **GATE**: use the already-loaded [`modes/_index.md`](./modes/_index.md) as the sole mode-basis catalog authority. After the three direction intents exist and their mode reference ids are frozen, read only those exact sibling files once; a novel mode reads none. |
| 135 | |
| 136 | The deck's **narrative + persuasion skeleton** — how the argument is organized and advanced. Lock one preset from `pyramid` / `narrative` / `instructional` / `showcase` / `briefing`, or `custom` with behavior. |
| 137 | |
| 138 | **Source**: |
| 139 | - User supplied their own outline / structure → preserve its facts and intended relationships, then apply the confirmed `content_divergence`. Treat an ordinary source outline as a Reference: regroup, reorder, or retitle when the communication contract benefits. Treat it as authoritative only when the user presents it as the final page plan or explicitly asks to preserve page order, titles, or wording; record that promoted boundary in `design_spec.md`. Still lock a mode for register, voice, and any permitted reshaping. `briefing` imposes the least if no particular "讲法" is intended. |
| 140 | - Beautify / re-layout profile ([`beautify-pptx.md`](../workflows/profiles/beautify-pptx.md)) → the extracted source content is authoritative and **verbatim**, one step stricter than the user-outline case above. Each source slide becomes exactly one `§IX` page in source order; transcribe every content block word-for-word — never reshape / re-primary / condense / merge / split / reword. All three custom mode behaviors preserve that 1:1 boundary and may share `briefing` as their sole basis; do not manufacture narrative variation. Color (e) and typography (g) are whatever the user confirmed in the beautify plan — the source identity (theme or observed) by default, or a content / brand-aware alternative the beautify plan offered and the user picked — locked as truth. Charts / tables / images are regenerated from their extracted data in the inherited style: record only selected catalog references in §VII, keep unmatched chart/table plans in their §IX page blocks, and route pictures to §VIII. Data values stay frozen and the rendering is the deck's own; visuals are never carried over verbatim. Layout, hierarchy, rhythm, and visual rendering are what gets redesigned. |
| 141 | - Each direction crystallizes one editable cadence / posture in `mode_behavior`. It is unconstrained by its relationship to the catalog and may use catalog material in any way or none, including carrying one preset unchanged. A catalog-based direction retains only the exact ids it actually uses; a direction using no catalog material invents no basis. One deck locks one `custom` value, never several simultaneous modes. |
| 142 | - No user structure or cadence → derive each whole solution from the confirmed `communication_intent`, `audience_outcome`, source texture, and delivery context, then project its custom mode. Directions may share catalog bases or the same mode behavior when their complete solutions remain plainly different; never force mode variation merely to separate the bundles. |
| 143 | |
| 144 | Record the confirmed mode and rationale in `design_spec.md` first, including every exact catalog basis when a selected custom uses any. Then project `- mode:` to `spec_lock.md`; for `custom`, also project `- mode_behavior:` and, only when catalog material is actually used, `- mode_references: <id>[, <id> ...]`. Executor reads only those exact references; an unreferenced novel custom follows the behavior directly. |
| 145 | |
| 146 | #### Layer 2 — Visual style |
| 147 | |
| 148 | 🚧 **GATE**: use the already-loaded [`visual-styles/_index.md`](./visual-styles/_index.md) as the sole style-basis catalog authority. After the three direction intents exist and their style reference ids are frozen, read only those exact sibling files once; a novel style reads none. |
| 149 | |
| 150 | The deck's **visual aesthetic** — shape language, decoration density, whitespace rhythm, typographic character, texture. Anchors downstream fields e (Color), f (Icon), g (Typography), h (Image). Lock one preset from the catalog, or `custom`. |
| 151 | |
| 152 | **Source**: |
| 153 | - User named a style (chat / template / beautify) → it is truth: retain it as the required basis or inherited anchor in every custom behavior. Derive each direction's application through the style dimensions left open. When the user or template forbids all visual variation, the three style behaviors may be identical and the remaining open components carry the direction difference; state that boundary in the direction note instead of fabricating difference. |
| 154 | - No user description → author three project-fit whole solutions first, then project one complete custom aesthetic for each. A custom aesthetic is not constrained by its relationship to the catalog; it may use catalog material in any way or none, including carrying one fitting style unchanged. Directions may share catalog bases, and their `visual_style_behavior` values differ whenever the three designs genuinely differ in aesthetic rather than to satisfy a variation quota. Do not force different bases, a safe-to-bold ladder, or one deliberately extreme option merely to manufacture variety. Give each direction a localized name and use its localized note as a compact, user-facing style summary. The note may reuse localized display labels from Confirm UI's `visual_styles` catalog (for example, `瑞士极简`, `柔和圆角`, or `编辑出版`) when they concisely describe the result, but these labels are optional vocabulary, not a selection constraint or required mapping. Use concise natural language wherever the catalog wording does not fit, and never force the nearest label. Keep the summary to one or two short sentences without exposing catalog ids or reference mechanics. The Confirm UI exposes these three project-specific styles above all 18 fixed manual alternatives. |
| 155 | |
| 156 | **Forbidden — a non-catalog name as `visual_style`**: every direction recommendation uses literal `custom` for `visual_style`; bespoke prose belongs only in `visual_style_behavior`, while optional `visual_style_references` contain only first-column catalog ids. A name from the `_index` "Paired rendering" column (`flat`, `vector-illustration`, `digital-dashboard`, `3d-isometric`, `corporate-photo`, …) is an image-rendering id, not a style reference. Generic words such as flat / modern / clean / simple / minimal are also insufficient behavior: use the index to choose an exact basis when applicable, then state the executable shape language, composition, density, whitespace, typography, and texture carried into this direction. Those rules may match one preset exactly; do not invent a difference merely to justify `custom`. |
| 157 | |
| 158 | **Carries no color.** A visual style governs how the deck's HEX (locked at `e`) is *used* — never which colors, same discipline as [`image-renderings`](./image-renderings/_index.md). When the deck has AI images, prefer the style's paired rendering so layout and illustration share one aesthetic. |
| 159 | |
| 160 | Record the confirmed visual style and rationale in `design_spec.md` first, including every exact catalog basis when a selected custom uses any. Then project `- visual_style:` to `spec_lock.md`; for `custom`, also project `- visual_style_behavior:` and, only when catalog material is actually used, `- visual_style_references: <id>[, <id> ...]`. Executor reads only those exact references; an unreferenced novel custom follows the behavior directly. |
| 161 | |
| 162 | **Conditional template workspace**: When the Stage-1 template choice has been installed into `<project_path>/templates/`, read [`strategist-template.md`](./strategist-template.md) before completing Stage 2. Read the installed project-local spec and prototypes only; never reopen the library/external source root. The module owns the editable natural-language application plan, confirmed-value consumption, AI-authored prototype selection, internal reuse/adherence derivation, inherited design precedence, and structured-lock planning. This plan decides how to use the installed template, never which template to select. Bare names, style words, and free-design projects do not trigger it. |
| 163 | |
| 164 | **Downstream effect**: e / f / g / h realize the locked mode + visual style. Example: `showcase` + `dark-tech` → e applies one luminous accent on a dark field; g pairs a clean sans with mono; f minimal glow icons; h the `digital-dashboard` rendering. |
| 165 | |
| 166 | ### e. Color Scheme Recommendation |
| 167 | |
| 168 | **Hard rule**: User-specified colors are truth. Lock supplied HEX, brand colors, or natural-language directives; templates follow inherited-design precedence. Even direct locks fill all six roles (`background`, `secondary_bg`, `primary`, `accent`, `secondary_accent`, `body_text`) in each of the three directions: repeat fixed roles and vary only open ones. Never emit an empty palette. Keep body-text contrast at least 4.5:1 and preserve confirmed/brand semantic roles. |
| 169 | |
| 170 | **Reference — not a constraint**: Without user/template colors, propose project-specific directions from content and style. `scripts/config.py` industry colors and dominant/support/accent hierarchy are recall aids, never default locks, ratios, or color-count quotas. |
| 171 | |
| 172 | **Lock recurring semantic anchors, not every possible paint.** Add the neutral roles already known to recur across the deck—such as `surface`, `grid`, `scrim`, `overlay`, or `block-shade`—when the visual style and page plan establish a stable meaning for them. Do not try to predict every page-local tint, gradient stop, shadow/glow color, transparency composite, or one-off illustration tone. Those values are chosen from page context during execution; promote one into `spec_lock.colors` only when it becomes a reusable named role. |
| 173 | |
| 174 | | Style trait | Extra neutral tiers to lock | |
| 175 | |---|---| |
| 176 | | Layers panels / charts (e.g. `data-journalism`, `swiss-minimal`) | `surface` (panel lift), `grid` (hairline, lighter than dividers) | |
| 177 | | Text over imagery / dark field (e.g. `photo-editorial`, `glassmorphism`, `dark-tech`) | `scrim` / `overlay` for legibility | |
| 178 | | Print / hand-drawn fills (e.g. `chalkboard`, `zine`) | `block-shade`, one step off the field | |
| 179 | |
| 180 | ### f. Icon Usage Confirmation |
| 181 | |
| 182 | The base icon style is one single-select identity, not a material whitelist: |
| 183 | |
| 184 | | Option | Approach | Suitable Scenarios | |
| 185 | |--------|----------|-------------------| |
| 186 | | **A** | Emoji | Casual, playful, social media | |
| 187 | | **B** | Built-in generic icon library | Recurring compact semantic cues in one coherent SVG style | |
| 188 | | **C** | Custom project icons | Supplied, template-carried, or imported assets | |
| 189 | | **D** | No base icons | Illustration, typography, shapes, or data already carry the compact cues | |
| 190 | |
| 191 | AI-generated illustrated icons are not a base-style option, add-on, Confirm UI |
| 192 | field, or result key. Like decorative lettering, they are a downstream image |
| 193 | carrier that §h and [`strategist-image.md`](./strategist-image.md) may choose |
| 194 | proactively when AI imagery is appropriate. Their transparent slices stay |
| 195 | under `images/`; never put them under `icons/`, add them to `icons.inventory`, |
| 196 | or reference them through `<use data-icon>`. |
| 197 | |
| 198 | Base SVG/emoji icons and illustrated-icon slices may be combined when the page |
| 199 | benefits, as long as the overall visual treatment remains coherent. Real brand |
| 200 | marks remain identity assets rather than another stylistic library. |
| 201 | |
| 202 | The built-in icon library contains multiple stylistic libraries plus a brand-logo library: |
| 203 | |
| 204 | See [`../templates/icons/README.md`](../templates/icons/README.md) for the current library inventory, counts, prefixes, and SVG placeholder details. |
| 205 | |
| 206 | Content-driven brand preparation applies under every base choice: if a real |
| 207 | company, product, service, or social identity appears and its mark improves |
| 208 | recognition, prepare the exact supplied or `simple-icons` asset; otherwise do |
| 209 | not add one. This requires no extra user-facing option. |
| 210 | |
| 211 | > **Mandatory rules for bundled SVG resources**: |
| 212 | > |
| 213 | > **At the Strategist confirmation stage — decide the generic base library and stroke only; resolve generic and content-driven brand filenames after approval.** |
| 214 | > |
| 215 | > 1. **Pick at most one primary stylistic library from the four bundled choices** — when generic icons are needed, read the source material and choose the one whose visual character best serves the deck: |
| 216 | > - **`chunk-filled`** — fill, straight-line geometry (M/L/H/V/Z only); sharp right angles; heavy, solid, architectural |
| 217 | > - **`tabler-filled`** — fill, bezier curves and arcs (C/A); smooth, rounded, organic; medium weight, approachable |
| 218 | > - **`tabler-outline`** — stroke (line art); airy, refined, lightweight; best for screen-only (thin strokes may be hard to read in print) |
| 219 | > - **`phosphor-duotone`** — duotone; main shape + 20% opacity backplate; medium weight, layered, contemporary |
| 220 | > - During bundled-library selection, do not select generic icons from more than one of `chunk-filled` / `tabler-filled` / `tabler-outline` / `phosphor-duotone`. If the chosen library lacks an exact icon, find the closest alternative **within that same library**. |
| 221 | > - **`simple-icons` is never a Confirm UI choice**: it is a brand-logo resource that Strategist prepares only when the actual content needs a real company / product / service mark (customer logos, tech-stack icons, social handles). It may be used with any base selection, including `none`, and never substitutes for a missing generic icon. |
| 222 | > - This restriction governs Strategist selection from the bundled catalog, not the prepared project asset pool. User-provided, template-carried, imported, custom, and previously prepared files under `<project_path>/icons/` remain valid material regardless of namespace or visual style. |
| 223 | > 2. **Stroke weight lock (stroke-style libraries only)** — for stroke-based libraries (currently `tabler-outline`), pick one deck-wide value from `{1.5, 2, 3}` (default `2`). For heavier presence, switch library instead of going above `3`. |
| 224 | > |
| 225 | > **After the Strategist confirmation stage is approved — when writing `design_spec.md` §VI / `spec_lock.md`**, materialize a curated project icon pool: |
| 226 | > |
| 227 | > 3. Choose a reusable set that covers recurring semantics and likely slide needs in the confirmed outline. Do not preassign individual icons to pages or add filler to meet a quota. |
| 228 | > 4. Put known basenames in the final batch. For an uncertain one, search the chosen style library — or `simple-icons` for a real brand mark — with `rg --files "skills/ppt-master/templates/icons/<library>" -g '*<drawable-object>*.svg'`. Abstract concept words return nothing; translate the semantic into a drawable object first, per [`../templates/icons/README.md`](../templates/icons/README.md). Do not enumerate broad keyword families. |
| 229 | > 5. **Copy and validate in one batch** — run `python3 skills/ppt-master/scripts/icon_sync.py <project_path> <lib/name> [<lib/name> …]`. This both validates and materializes `<project>/icons/<lib>/`; skip per-file prechecks. |
| 230 | > 6. Keep each successful, case-sensitive `lib/name`: bundled basenames are lowercase (`tabler-outline/award`, never `tabler-outline/Award`); custom icons retain exact case. |
| 231 | > 7. Record each synced bundled path with broad suitable scenarios in `design_spec.md` §VI; record the same curated pool, its primary stylistic library, and any stroke-library `stroke_width` in `spec_lock.md icons`. Keep actually needed `simple-icons/*` ids in the same inventory without treating them as a second stylistic library or user-facing selection. The pool is prepared optional material, not a page-use plan, coverage quota, or whitelist over other prepared project-local icons. |
| 232 | > |
| 233 | > 🚧 **GATE — missing icon = re-pick now**: on non-zero exit, search a missing generic concept only in the chosen stylistic library, or a missing real brand mark in `simple-icons`; re-pick and rerun the final batch until clean. Never carry a missing icon forward or switch among the four stylistic libraries to fill the gap. |
| 234 | > |
| 235 | > **Default — targeted lookup only**: do not load or rebuild a full index; search only unresolved concepts. |
| 236 | |
| 237 | ### g. Typography Plan Confirmation (Font + Size) |
| 238 | |
| 239 | 🚧 **GATE**: Apply the chosen custom behavior and only the detail files already loaded from its exact `visual_style_references`. The title carries the character; the body may remain neutral. |
| 240 | |
| 241 | **Family selection**: |
| 242 | |
| 243 | - User/template typography is authoritative. Repeat fixed stacks with `typography.fixed: true` in every direction; never vary them for diversity. Keep the three directions distinguishable as full bundles; reasonable font repetition is non-blocking, with no extra font round. |
| 244 | - Every Stage-2 direction carries `heading` / `body` `primary`, `css`, and positive `body_size`; add `english` only when the deck's main language is not English. |
| 245 | - Resolve the delivery target under [`shared-standards-core.md`](./shared-standards-core.md) §4.1, then use concrete, target-installed/approved PowerPoint faces. The Confirm UI font catalog supplies additional manual dropdown choices, not a recommendation whitelist. |
| 246 | - Keep stacks to four families or fewer. A brand/web face may lead only after user-confirmed target installation/approved install; PPT Master does not embed fonts. Otherwise export a safe face and keep the unavailable face as Design Spec reference. |
| 247 | - Avoid near-equivalent role splits such as YaHei↔PingFang, SimSun↔Songti, Arial↔Helvetica↔Segoe UI, or Times New Roman↔Times. Counterparts may aid SVG/browser preview; CSS tails are not deterministic PowerPoint fallbacks. |
| 248 | - Choose by locked style and vary the axis: serif×sans, Kai/FangSong×hei, hei×song, double-serif, display×neutral, same-family weight, or sans+mono. These are recall seeds, not presets. |
| 249 | |
| 250 | **Strategist-owned role extension after confirmation**: Confirm UI keeps the heading/body choice unchanged. While authoring the complete §IX roster and §IV typography plan, scan the actual content for recurring roles that materially need a different family for character or legibility—such as `annotation`, `footer`, `footnote`, `data`, `emphasis`, `quote`, or `code`. Add a lowercase snake_case role and exact stack only when it recurs; inherited roles and one-off garnish stay omitted. The extension must remain coherent with the confirmed heading/body system and locked visual style, and it does not reopen confirmation. Only when an additional family role is added, record one compact `Role rationale` in §IV naming the added role(s) and why; otherwise omit the line. |
| 251 | |
| 252 | **Size anchors — px only**: Every authoring layer carries bare px numbers. PowerPoint's displayed pt is an export result (`px × 0.75`), never an input or confirmation value. |
| 253 | |
| 254 | **Mandatory — canvas-owned body start**: Read |
| 255 | [`canvas-formats.md`](canvas-formats.md) § "Typography Scale Start" before |
| 256 | authoring size candidates. It owns the initial body anchor and sanity band for |
| 257 | PPT reading modes plus registered/custom non-PPT canvases; do not reproduce or |
| 258 | rederive them here. The confirmed role-anchor values always win: take Confirm UI |
| 259 | `body_size` / `sizes` verbatim as anchors; a manually edited anchor remains |
| 260 | pinned, and changing canvas does not secretly rescale it. |
| 261 | |
| 262 | | Recurring role | Ratio to body | |
| 263 | |---|---:| |
| 264 | | Cover title / single-focus hero | 2.5–5× | |
| 265 | | Chapter title | 2–2.5× | |
| 266 | | Page title / KPI hero | 1.5–2× | |
| 267 | | Subtitle | 1.2–1.5× | |
| 268 | | Lead / subheading | 1.1–1.4× | |
| 269 | | Body | 1× | |
| 270 | | Annotation | 0.7–0.85× | |
| 271 | | Footnote / page number | 0.5–0.65× | |
| 272 | |
| 273 | Scan §IX before locking. Declare every recurring role, including `lead`, `footnote`, and chart annotations when used; a lead is always at least body size. Give each role one deck-wide anchor and snap derived anchors to clean even px (for body 24, a sound set is title 42, subtitle 32, lead 30, annotation 18, footnote 16). Executor may vary one occurrence within that role's anchor ±2px while preserving hierarchy and readability. A short non-structural Hero/Display size planned for at most two occurrences may remain undeclared; the third planned occurrence makes it recurring and requires an explicit named slot. Structural text never uses this sparse exception. |
| 274 | |
| 275 | #### Mathematical Content Planning |
| 276 | |
| 277 | Preserve every source-backed equation and its mathematical meaning. In each |
| 278 | applicable §IX page block, record the exact expression under `Mathematical |
| 279 | content` in the canonical form: a LaTeX body without `$...$`, `$$...$$`, |
| 280 | `\(...\)`, or `\[...\]` source delimiters. This field may cover any mathematics that needs exact |
| 281 | preservation; do not classify it as inline or structural or choose its |
| 282 | implementation. Never invent an equation for decoration or create a formula |
| 283 | policy, manifest, PNG, §VIII row, or `spec_lock.md images` entry. Executor owns |
| 284 | the text-versus-native-formula decision and its authoring; if the documented |
| 285 | Microsoft 365 input profile cannot preserve the planned content, return here for a |
| 286 | content-level correction. |
| 287 | |
| 288 | #### Hyperlink Content Planning |
| 289 | |
| 290 | Preserve every explicit or source-backed link intent. In the applicable §IX |
| 291 | page block, record the linked text/object and its exact absolute URI or final |
| 292 | 1-based same-deck slide target. Never guess an external destination, select the |
| 293 | inline/whole-object carrier, or create a link manifest or lock entry. Executor |
| 294 | owns SVG authoring under [`native-hyperlinks.md`](./native-hyperlinks.md). |
| 295 | |
| 296 | ### h. Image Source Recommendation |
| 297 | |
| 298 | | Source id | Approach | Use when | |
| 299 | |---|---|---| |
| 300 | | `none` | No images | Data reports or process documentation whose visual burden is fully served by charts / native SVG | |
| 301 | | `provided` | User-provided assets | Existing images carry factual, brand, product, or narrative authority | |
| 302 | | `ai` | AI-generated | Invented or deliberately stylized scenes, illustrations, backgrounds, metaphors, decorative lettering, or another generated visual treatment is needed | |
| 303 | | `web` | Web-sourced | A named or evidence-bearing real-world subject must appear as itself | |
| 304 | | `placeholder` | Deferred | The image is required but will be supplied later | |
| 305 | |
| 306 | **Current inventory**: If `images/` is non-empty, run `python3 scripts/analyze_images.py <project_path>/images` and read `analysis/image_analysis.csv` before recommending a source. Re-run after that folder changes. |
| 307 | |
| 308 | **Hard rule**: Credentials do not decide image need. Missing `IMAGE_BACKEND`, host generation, or keyed stock-provider credentials never justifies `none` or deletion of a planned web-compatible role. Web search retains zero-config providers; an explicit generation-only requirement follows the normal Offline Manual boundary. |
| 309 | |
| 310 | **Mandatory — no AI capability preflight**: When `recommend.image_usage` includes `ai`, preserve an explicit user path instruction; otherwise recommend `auto`. Do not inspect backend configuration, check host-tool availability, or probe a provider during planning. Generate Step 5 execution is the first capability check. |
| 311 | |
| 312 | **Default — visual grounding before `none` (may override when the full-roster carrier review finds no useful image job)**: Honor an explicit no-image requirement. First decide whether the audience must recognize, experience, compare, or choose an externally verifiable subject, place, product, or setting. When yes, propose `provided` / `web`; propose `ai` when invented or deliberately stylized expression materially improves a planned visual job. Treat `none` as a positive whole-deck conclusion when no image source owns a meaningful communication job. Mixed sources may serve different page roles. The three Stage-2 style directions never settle source: a rendering candidate resolves how imagery looks, never whether a real subject must appear as itself. |
| 313 | |
| 314 | **Default — consider proactive illustrated icons without creating another |
| 315 | confirmation field**: Before each Stage-2 `recommend.image_usage`, consider |
| 316 | whether compact semantic jobs would communicate better through a coherent |
| 317 | illustrated cue family. This may support an `ai` recommendation, but it is not |
| 318 | an automatic source trigger or coverage quota. Resource grouping remains a |
| 319 | fit-driven decision under [`strategist-image.md`](./strategist-image.md). |
| 320 | |
| 321 | **Mandatory — scan proactive decorative-lettering capability without making |
| 322 | candidates an automatic source trigger**: Before each Stage-2 |
| 323 | `recommend.image_usage`, scan the complete planned roster for exact stable |
| 324 | display strings whose artistic treatment could plausibly communicate better |
| 325 | than native type. Page role, character count, word count, line count, kind of |
| 326 | noun, and proposed style never pre-filter candidates: a complete long or |
| 327 | multi-line title is as eligible as a short mark. Never invent, rewrite, |
| 328 | shorten, or split copy to make generation easier. Passing both discovery |
| 329 | questions exposes one possible AI visual job, not a selected resource or a |
| 330 | mechanical reason to add `ai`. During page-carrier planning, compare those |
| 331 | candidates with native type and the complete deck mix; select only the marks |
| 332 | whose treatment wins that fit. Zero selected marks remains valid and needs no |
| 333 | skip explanation or coverage quota. A selected mark may be the sole intended |
| 334 | AI job and may support an AI recommendation stated in `image_notes.value`; |
| 335 | when either discovery answer is no, native editable text remains valid. The |
| 336 | absence of another AI-image job never forces lettering. Explicit no-AI or |
| 337 | editable-only requirements win. Execution follows |
| 338 | [`image-generator.md`](./image-generator.md) §7. |
| 339 | |
| 340 | **Recommendation output**: Write `recommend.image_usage` as one source id or an array for mixed sources. Put the intended communication jobs of each proposed source, authoritative assets, preferred/avoided imagery, and placeholder tolerance in `image_notes.value`. When `ai` is proposed, explain in editable natural language how generated visuals are expected to contribute and mention any materially anticipated illustration, illustrated-icon, or lettering role. Keep the note an open strategy—not an enum, carrier allowlist, page-by-page assignment, count, or resource manifest; name exact pages/assets only when already authoritative or required. `none` is exclusive. Decks built around real-world recognition or choice, including travel itineraries, lean `provided` / `web`; generic human-scale topics such as family life, education, wellness, or children lean `ai` when no supplied asset carries the story and invented or stylized expression serves it. Regulated investor decks, B2B finance reports, and data-only dashboards remain eligible for `none` by judgment. |
| 341 | |
| 342 | **Confirmed value wins**: Accept the confirmed legacy string or multi-select array. Map `ai→ai`, `web→web`, `provided→user`, and `placeholder→placeholder` into §VIII `Acquire Via`. Every direction already carries a rendering candidate whether or not AI is proposed; generated images inherit the deck colors and never introduce a second image-palette choice. |
| 343 | |
| 344 | **Always-on decision module; conditional resource extension**: |
| 345 | |
| 346 | 1. Before authoring Stage-2 directions, load the workflow's complete fixed |
| 347 | planning-capability batch. It includes this module, the image-layout |
| 348 | authorities, all compact decision maps, the icon-library contract, the |
| 349 | complete Chart and Table expression vocabularies. After the |
| 350 | three whole-direction intents exist and their mode/style/rendering reference |
| 351 | ids are frozen, read only |
| 352 | those exact detail siblings once and author one complete custom rendering |
| 353 | inside each direction before deciding whether `recommend.image_usage` |
| 354 | includes AI. |
| 355 | 2. Independently derive `recommend.image_usage` from source needs. Confirmed |
| 356 | non-`none` sources activate the module's resource-planning sections. |
| 357 | Confirmed `none` writes no image rows, but does not erase the three |
| 358 | recommendation-only rendering candidates or the already-loaded composition |
| 359 | vocabulary. |
| 360 | |
| 361 | The module owns AI rendering alternatives, acquisition paths, resource rows, prompt depth, page roles, and placement intent. |
| 362 | |
| 363 | ### Page Carrier and Capability Planning (Non-blocking — Strategist recommends, no user confirmation needed) |
| 364 | |
| 365 | **Mandatory — one-pass page carrier planning**: During the same §IX roster |
| 366 | composition, resolve each page's complete semantic carrier mix—background |
| 367 | field, editable text and optional lettering, native-geometry/relationship jobs, |
| 368 | photos/scenes/illustrations/icons, and applicable visualizations—before |
| 369 | deriving §VIII resource rows. Decide the primary, structural, and supporting |
| 370 | jobs together; do not finish a text/container layout and then treat the other |
| 371 | families as optional decoration. Use existing §VI/§VIII/§IX fields: keep the |
| 372 | ordinary icon basis and prepared-pool plan in §VI, and add an image, lettering, |
| 373 | or illustrated-icon resource to §VIII only when the page mix assigns it a |
| 374 | plausible job. This creates no new field or candidate inventory; omitting any |
| 375 | carrier remains valid after the same review. Macro composition recommendations |
| 376 | remain Reference; planned resource identities/jobs and explicit user/template |
| 377 | requirements retain their existing authority. |
| 378 | |
| 379 | **Hard rule — native construction stays downstream**: record the page's |
| 380 | semantic relationships, prepared resource roles, and any useful macro |
| 381 | composition or visual-system recommendation. Do not inventory or bind a preset, |
| 382 | primitive, Connector, Boolean/freeform operation, coordinates, or other local |
| 383 | authoring method as the construction plan. A technique may appear only as |
| 384 | optional inspiration inside a macro Reference; Executor independently |
| 385 | discovers and selects construction from the actual page content and visual |
| 386 | system. |
| 387 | |
| 388 | | Capability | Opportunity signal | Design Spec handoff | |
| 389 | |---|---|---| |
| 390 | | Image composition | Image-as-canvas, editorial crop, collage, cutout, or meaningful focus / comparison / evidence units carry the page better than an adjacent rectangle | Propose a permitted source; when selected, apply the already-loaded [`strategist-image.md`](./strategist-image.md) resource contract and image-layout references, record a concise §VIII `Layout pattern` suggestion, and describe page-level image/overlay relationships in §IX `Layout` / `Images` | |
| 391 | | Composable illustration family | One or more pages benefit from coherent reusable title/corner ornaments, dominant anchors, supporting figures, compact illustrated-icon cues, or accents that can mix with text, shapes, photos, or lettering | Apply [`strategist-image.md`](./strategist-image.md): plan transparent elements by compatible family, record fixed reuse or adaptive variation in §VIII `Reference`, and describe each used page's carrier relationships in §IX `Layout` / `Images` | |
| 392 | | Native paint / overlay | Gradient, translucency, scrim, vignette, or wash supports focus, hierarchy, depth, legibility, or image integration | Record purpose/layering in §IX `Layout`, plus `Images` when imagery participates; no new field or type/stops/opacity/coordinates—Executor chooses realization | |
| 393 | | AI decorative lettering asset | Any stable display string in the deck — including a complete long or multi-line title, cover hook, chapter word, place or product name, dish or exhibit name, year, hero number, pull quote, or motif word — reads better with a material, dimensional, hand-rendered, or otherwise illustrative treatment than as ordinary text | Apply [`strategist-image.md`](./strategist-image.md): preserve every complete exact string, group compatible marks when useful, and keep chrome/body as native text. The lettering asset may carry the complete long or multi-line title as its display layer; keep an ordinary native title/subtitle in a separate text frame wherever the page needs a searchable, selectable, or outline-visible heading. Never shorten copy to make it look more like a wordmark | |
| 394 | | Page transition | A section/state change, spatial continuity, recorded/self-running flow, or the same semantic object changing position, scale, crop, or state across adjacent pages benefits from motion | Add an optional §IX `Motion suggestion` describing the communication job and any continuing object's initial state → action → end state; leave effect, ids, pairing names, and timing to Executor | |
| 395 | | Object animation | Progressive reveal, emphasis, movement, removal, or deliberate stillness clarifies sequence, causality, comparison, hierarchy, narration order, full-view → detail, atmosphere → evidence, or hotspot/annotation order | Add an optional §IX `Motion suggestion` naming each relevant semantic unit's lifecycle duty and initial state → communication action → end state, plus any meaningful order/relationship; leave group ids, effects, options, and timing to Executor | |
| 396 | |
| 397 | **Reference — not a constraint: motion lifecycle vocabulary.** |
| 398 | |
| 399 | | Duty | Semantic lifecycle | |
| 400 | |---|---| |
| 401 | | `enter` | absent → introduce → present | |
| 402 | | `emphasize` | present → redirect attention → present/altered | |
| 403 | | `move` | state/position A → progress → state/position B | |
| 404 | | `exit` | present → retire → absent | |
| 405 | | `static` | present → hold as reference → present | |
| 406 | |
| 407 | Use only relevant duties—no category quota. For every unit mentioned in a |
| 408 | `Motion suggestion`, state its duty, lifecycle, and meaningful order; never |
| 409 | name an effect, target id, option, or timing. Write useful advice regardless of |
| 410 | the effective outcome. Suggestions remain non-binding and never activate the |
| 411 | custom stage; only an explicit motion requirement or an enabled outcome may |
| 412 | require visible lifecycle-state preparation. |
| 413 | |
| 414 | Classify by information model, never source PowerPoint object type: |
| 415 | |
| 416 | | Model | Planning action | |
| 417 | |---|---| |
| 418 | | Qualitative `order`, `link`, `parent`, `membership`, `contrast`, or `overlap` | Preserve units, relationship, and reading path as free §IX prose; no catalog key | |
| 419 | | Values/dates/durations determine geometry | Chart; compare the complete loaded chart expression vocabulary | |
| 420 | | Row header × column header addresses each fact | Table; compare the complete loaded Table expression vocabulary | |
| 421 | |
| 422 | **Mandatory — relationship handoff**: keep every qualitative relationship in §IX free prose; never serialize grammar atoms, coordinates, or named models. Executor makes the per-page Structure decision at runtime. |
| 423 | |
| 424 | **Mandatory — complete Chart/Table capability review**: During the same §IX |
| 425 | roster composition, compare every page's information model against every entry |
| 426 | in the already-loaded Chart and Table expression vocabularies. These |
| 427 | complete capability maps expose what can be selected; their descriptions do |
| 428 | not rank candidates or replace judgment from the actual information. They are |
| 429 | neither usage quotas nor whitelists. Skip custom objects and qualitative |
| 430 | composition. Retain `no-template-match` when no registered reference fits. |
| 431 | |
| 432 | **Selection**: |
| 433 | |
| 434 | 1. Choose at most one flexible Chart/Table `family/key` per page; keep children and qualitative relationships in §IX. |
| 435 | 2. If none fits, keep `no-template-match` and plan the fallback only in §IX; never serialize no-match. |
| 436 | 3. Validate every selected canonical reference before the lock: |
| 437 | |
| 438 | ```bash |
| 439 | python3 skills/ppt-master/scripts/visualization_recall.py validate \ |
| 440 | <family>/<key> [<family>/<key> ...] |
| 441 | ``` |
| 442 | |
| 443 | Correct failed selections by re-reading the complete vocabulary/registry; |
| 444 | `no-template-match` never enters `page_visualizations`. |
| 445 | |
| 446 | **Section VII selection list**: write `Page | Family | Template | Usage` for each `chart|table` reference; Usage is semantic purpose. Omit empty/no-match detail. Qualitative composition stays in §IX; only Layout/Deck owns reusable PowerPoint structure. |
| 447 | |
| 448 | **Native-ready boundary**: Give every independent data chart and pure text-grid table in §IX `Visualization` a unique page-local semantic `kebab-case` key, then write one `Native-ready` map: `<key>=yes|no; ...`. Decide `yes` by default; use `no` only when [`native-data-interface.md`](./native-data-interface.md) §2 cannot express that object. Qualitative shape compositions and incidental microvisuals stay unlisted. |
| 449 | |
| 450 | ```markdown |
| 451 | | Page | Family | Template | Usage | |
| 452 | | --- | --- | --- | --- | |
| 453 | | P03 | chart | line_chart | Compare the source metrics over time | |
| 454 | ``` |
| 455 | |
| 456 | ### Speaker Notes Requirements |
| 457 | |
| 458 | Resolve the effective Speaker Notes outcome from the latest explicit user |
| 459 | instruction, then final Stage 2 `proactive_speaker_notes`, then workflow default |
| 460 | `true`. Effective Narration Audio `enabled` requires Speaker Notes `enabled` |
| 461 | without changing the raw proactive preference; when that dependency changes the |
| 462 | notes outcome, its provenance names enabled Narration Audio. |
| 463 | |
| 464 | | Effective outcome | Design Spec §X | |
| 465 | |---|---| |
| 466 | | `enabled` | Record filename policy, content/source handling, total duration, notes style, and presentation purpose | |
| 467 | | `disabled` | Keep §X and write `Generation: disabled`; do not invent note requirements | |
| 468 | |
| 469 | When enabled, match SVG names where possible (`01_cover.svg` → |
| 470 | `notes/01_cover.md`); `notes/slide01.md` remains compatible. Split files contain |
| 471 | no `#` heading lines; `notes/total.md` uses `#` headings. |
| 472 | |
| 473 | **Prepared final narration**: when the user explicitly marks a script as |
| 474 | final/literal and intends it for notes or generated audio, preserve its wording |
| 475 | and order. Segment it by semantic scene while resolving §IX, record its source |
| 476 | and verbatim policy in §X `Content`, and let Generate write the frozen |
| 477 | `notes/total.md` only after the final roster and lock pass their gates. Do not |
| 478 | copy the full script into on-slide `Content` or rewrite it as visible body text. |
| 479 | |
| 480 | --- |
| 481 | |
| 482 | ## 2. Mode & Visual-Style Catalogs (Reference for Confirmation Item d) |
| 483 | |
| 484 | Confirmation `d` locks two independent catalog items: |
| 485 | |
| 486 | - **Mode** — narrative skeleton: [`modes/_index.md`](./modes/_index.md) → `pyramid` / `narrative` / `instructional` / `showcase` / `briefing`. |
| 487 | - **Visual style** — aesthetic: [`visual-styles/_index.md`](./visual-styles/_index.md) → presets + `custom`. |
| 488 | |
| 489 | Strategist first loads the fixed planning-capability batch. For |
| 490 | mode/style/rendering basis selection it uses only the three corresponding |
| 491 | indexes, freezes the bases for the three whole directions, then reads only the |
| 492 | deduplicated referenced detail files before authoring their custom behaviors. |
| 493 | Executor reads one locked preset file or the exact references of a selected |
| 494 | custom; neither role globs a detail catalog (see |
| 495 | [`generate-pptx`](../workflows/generate-pptx.md) Step 6). |
| 496 | |
| 497 | --- |
| 498 | |
| 499 | ## 3. Color Selection Reference |
| 500 | |
| 501 | Do not start from a universal palette. Precedence is user / brand → active template → project-specific proposal; `scripts/config.py` industry anchors are optional recall. Keep body-text contrast at least 4.5:1; color count and distribution follow encoding, style, and natural assets, not a quota. |
| 502 | |
| 503 | Lock the stable role set the deck needs, including recurring neutrals such as `surface`, `grid`, `scrim`, `overlay`, or `block-shade`. These are identity anchors, not an exhaustive paint list. Executor may derive tints, shades, alpha, gradients, and effects, preserve necessary natural asset colors, and add sparse page-local accents for differentiation or ornament. Such accents must not form a competing/recurring palette; Strategist owns reusable positive / warning / negative roles. |
| 504 | |
| 505 | --- |
| 506 | |
| 507 | ## 4. Layout Pattern Library |
| 508 | |
| 509 | **Reference — not a constraint**: use these patterns as macro recommendation vocabulary. Proportion follows information weight, not preset ratios. Recommend or combine the smallest direction that expresses the relationship; Executor may adopt, adapt, or decline it after reading the actual page content and visual system. Repeating symmetric card grids without a page job is a failure mode. |
| 510 | |
| 511 | | Content relationship | Useful starting structure | |
| 512 | |---|---| |
| 513 | | One focal claim | centered single column, negative space, or full-bleed + floating text | |
| 514 | | Equal comparison | symmetric split or a true matrix | |
| 515 | | Dominant evidence + takeaway | asymmetric split with one dominant field | |
| 516 | | Parallel sequence | three-column, process line, or Z-pattern | |
| 517 | | Core + surrounding forces | center-radiating or hub-spoke | |
| 518 | | Wide visual + explanation | top-bottom split | |
| 519 | |
| 520 | **Reference — not a constraint**: after the complete §IX roster and planned |
| 521 | visual resources are known, recommend a cross-page motif or coherent element |
| 522 | family when it can carry identity or meaning—such as title/corner ornaments, a |
| 523 | directional contour, opening, line lattice, or oversized numeral. Record its |
| 524 | continuity job and possible reuse mode in §III `Theme`; mention it only in §IX |
| 525 | `Layout` blocks that benefit. Executor may adopt, adapt, or decline it and owns |
| 526 | its geometry and construction. Create no motif field or lock row, and impose no |
| 527 | decoration quota. |
| 528 | |
| 529 | --- |
| 530 | |
| 531 | ## 5. Template Flexibility Principle |
| 532 | |
| 533 | **Reference — not a constraint**: free-design patterns are starting points, not quotas. Recommend a macro direction from the confirmed reading mode, page rhythm, and content; Executor owns exact composition and spacing within locked typography anchors. When a template workspace is active, do not reinterpret its reuse contract here; load [`strategist-template.md`](./strategist-template.md). |
| 534 | |
| 535 | ## 6. Workflow & Deliverables |
| 536 | |
| 537 | ### 6.1 Content Planning Strategy |
| 538 | |
| 539 | Content-outline strategy and, when enabled, speaker-notes strategy follow the deck's locked **mode** — see [`modes/_index.md`](./modes/_index.md), then the locked preset file or every listed custom reference plus its behavior. The guidance below applies within any mode: |
| 540 | |
| 541 | **Reading mode controls information carriage, not communication intent.** `result.json delivery_purpose` is retained as the compatibility key for `text` (read-close) / `balanced` (business, default) / `presentation`, confirmed with the complete deck solution in Stage 2. It decides how meaning is divided among the page, visuals, presenter, and enabled notes. The body baseline (§g) is one consequence, not the definition: |
| 542 | |
| 543 | | Reading mode | Primary carrier | §IX page grammar | Granularity / rhythm | Speaker notes | |
| 544 | |---|---|---|---|---| |
| 545 | | `text` · read-close | page / document | complete assertions, short prose paragraphs, captions, tables, and necessary detail; bullets only for genuinely parallel or ordered items | fewer, fuller pages; leans `dense` | supplemental context, not a substitute for missing page logic | |
| 546 | | `balanced` · business (default) | page + presenter | one primary claim with concise explanation, structured evidence, or a necessary list | moderate granularity; mixed rhythm | interpretation and transitions | |
| 547 | | `presentation` | presenter + visuals | one claim per page, keywords / short phrases, a large visual or hero number; no paragraph dumps or prose compressed into bullet fragments | more, sparser pages; leans `anchor` / `breathing` | carries explanation, transitions, and supporting detail | |
| 548 | |
| 549 | When Speaker Notes is disabled, the final column is unavailable: keep every |
| 550 | required meaning in the visible page and confirmed presenter channel. |
| 551 | |
| 552 | **Recommendation signals**: derive the initial reading mode from the confirmed `audience`, `delivery_context`, and `artifact_afterlife`. Asynchronous review, reference, approval, audit, and leave-behind use lean `text`; presenter-led projection, large-room delivery, launch, or classroom explanation lean `presentation`; hybrid review / roadshow use leans `balanced`. When live projection and durable afterlife both matter, recommend `balanced` unless the contract clearly prioritizes one. If the user confirms `presentation`, support afterlife through enabled notes, appendix pages, captions, and visible sources instead of crowding every slide. |
| 553 | |
| 554 | **Default — visible-state sequence (may override when a new composition is clearer)**: Before freezing the §IX roster and enabled notes/narration boundaries, compare adjacent semantic beats within the active profile's roster/content invariants. When recurring roles, relationships, and spatial orientation form one mental map and the next beat has a meaningful state or focus change, plan neighboring pages as visible states of that scene: preserve recognizable anchors, make the semantic delta legible, and align each enabled notes/narration segment with its supporting visible state. This is a content-and-rhythm strategy, not a page quota. Reset the composition when the mental map changes or continuity adds no clarity. Within the confirmed page count, every state page must carry content and an `Audience move`; the effective motion outcome changes realization, not roster authority. |
| 555 | |
| 556 | **Per-block expression**: let the semantic relationship choose the form. Causal explanation, argument, interpretation, and narrative continuity use prose. Truly parallel, ordered, or enumerable items may use bullets / numbers. Never create bullets merely because copy is long or a template exposes a list slot. In `presentation`, distill one assertion and move its explanation into enabled notes rather than turning every sentence into a fragment; when notes are disabled, keep the necessary explanation in the visible page or confirmed presenter channel. Source texture remains a secondary cue: an article / transcript / talk leans prose, while a data sheet or inventory may lean structured labels. Write complete, usable phrasing into §IX; do not leave skeletons for Executor. It is preferred wording unless literal preservation applies; Executor owns faithful expression adaptation under [`executor-base.md`](./executor-base.md) §2.1's content-vs-expression contract. |
| 557 | |
| 558 | This is what makes the axis meaningful: a `presentation` deck and a `text` deck built from the **same source and communication contract** must differ in page grammar, page count recommendation, per-page text volume, visual burden, layout density, rhythm, and enabled notes—not only in font size. Page count stays the user's call; reading mode informs the recommendation when the user has not fixed one. Record it as **Reading Mode** in `design_spec.md §I` (compatibility key `delivery_purpose`, lock key `consumption_mode`). Separately, `communication_intent` / `audience_outcome` determine what the outline must accomplish, while `delivery_context` and `artifact_afterlife` help select the reading mode and still remain independent constraints after selection. The `page_rhythm` leans are a bias, not a quota. Preservation paths keep source wording and structure verbatim: honor reading mode only in styling and enabled notes, never by rephrasing or re-paginating. |
| 559 | |
| 560 | > Note: §IX is the complete page brief; Executor retains it with the lock until context invalidation, then reloads both once. |
| 561 | |
| 562 | ### 6.2 Planning Artifact Content |
| 563 | |
| 564 | Generate Step 4 owns this sequence. `design_spec.md` is the complete human-readable decision; `spec_lock.md` is its context-selected execution subset/routing contract. Consume `result.json` once into the initial Design Spec and never reopen it for the lock. Refinement edits that same Design Spec; affected user revisions become the latest authority. Never treat the planning files as parallel interpretations. |
| 565 | |
| 566 | After final confirmation, a newer explicit notes/animation/narration instruction |
| 567 | updates only affected §I outcomes/provenance and resumes their owner; never |
| 568 | reopen Confirm UI or add them to `spec_lock.md`. Before editing, apply |
| 569 | Generate's notes/audio dependency gate. Record animation provenance as |
| 570 | final Stage 2 `false`, explicit objects-off, or explicit all-motion-off; only the last |
| 571 | includes transitions. |
| 572 | |
| 573 | 1. With Generate Step 4's retained complete final-confirmation state, read `${SKILL_DIR}/templates/design_spec_reference.md`. |
| 574 | 2. Compose the whole Design Spec in active context before touching the target path. Create `design_spec.md` once from the schema marker through §X; do not copy a scaffold into the project or patch placeholder fields. Record production mechanics in §I, including one effective outcome plus provenance for Speaker Notes, Custom Animations, and Narration Audio. Resolve them from latest explicit user instruction → matching final Stage 2 proactive value → workflow default `enabled` / `disabled` / `disabled`; Narration Audio enabled requires Speaker Notes enabled without rewriting the raw proactive evidence, and a dependency-driven notes outcome records that provenance. In §IX, create the complete ordered roster; each entry carries layout, title, core message, **Audience move**, complete preferred wording, exact mathematical content when applicable, capability recommendations, visualization/image references, sourced `Fact IDs`, and `Data class: scenario` for invented demo data. After Gate 1 plus conditional refine approval, roster ids/count/order and semantic content are authoritative; non-literal wording, block texture, layout, cover/closing composition, capability recommendations, and image/visualization patterns remain References unless promoted, so Executor may adopt, adapt, or decline them without upstream repair while preserving their semantic jobs and all binding constraints. |
| 575 | 3. Compare `design_spec.md` against the final confirmation field by field. Repair every omission or deviation before entering an enabled refine-spec review or authoring `spec_lock.md`. |
| 576 | 4. If enabled, run [`refine-spec`](../workflows/stages/refine-spec.md) after Gate 1; edit only that Design Spec and create no lock before explicit approval. |
| 577 | 5. Read `${SKILL_DIR}/templates/spec_lock_reference.md`; create the lock once or resynchronize stale derived state from the approved Design Spec and context. Retain identity/refinements and stable roles/routing; omit unnamed page-local values, do not reopen evidence, and make no new recommendation. |
| 578 | |
| 579 | **Final confirmation → Design Spec consumption map**: |
| 580 | |
| 581 | | Confirmed state | Required Design Spec realization | |
| 582 | |---|---| |
| 583 | | Communication contract and `content_divergence` | §I records the confirmed contract; §IX realizes every stated purpose, outcome, priority, and source-treatment constraint | |
| 584 | | Canvas, reading mode, and page count | §I records the confirmed input and exact resolved count; §IX contains that many ordered pages. Executor produces exactly one output slide per entry, in order | |
| 585 | | Mode, visual style, palette, and generated-image rendering | §I and §III record the selected direction as identity anchors; named core roles stay stable while page-local expression remains contextual | |
| 586 | | Typography, including Strategist-derived recurring family overrides and every visible role size | §IV records Character/upgrade References, resolved heading/body stacks, recurring support-role stacks justified by §IX, and exact `body`, `title`, `subtitle`, and `annotation` anchors; never discard a declared role override or re-derive a confirmed anchor | |
| 587 | | Icons | §VI records the confirmed base library/no-icon/custom path and any content-driven `simple-icons` brand marks; illustrated-icon families are planned as AI image resources in §VIII and require no separate confirmation choice | |
| 588 | | Confirmed image-source set, `image_notes`, and AI strategy | §VIII uses only permitted sources and includes every explicitly required source, asset, or page role; a permitted but unused source needs no row | |
| 589 | | Natural-language template application | §I records it and the relevant layout/prototype choices realize it without silently dropping a requested use or exclusion | |
| 590 | | AI-image acquisition path, generation mode, refine-spec toggle | §I records them as production mechanics; their owning Generate stage consumes the Design Spec | |
| 591 | | Proactive speaker notes, custom animations, and narration audio | §I records the three resolved effective outcomes with provenance, while §X records enabled note requirements or `Generation: disabled`; they remain outside `spec_lock.md`. §IX Motion suggestions remain optional advice regardless of the animation outcome | |
| 592 | | Explicit final/literal narration script | §IX segments the argument by semantic scene and gives each segment a supporting visible state; §X records the source plus verbatim policy, and Generate freezes the actual segments in `notes/total.md` after Gate 2 | |
| 593 | |
| 594 | ⛔ **GATE 1 — active-decision fidelity.** Do not create `spec_lock.md` until the initial Design Spec passes the comparison above and any enabled refinement is explicitly approved. Before Gate 2, every requested revision must be present and every unaffected decision intact. Missing/substituted values, unapplied revisions, or silently changed semantic types block despite schema validity; bounded Reference adaptation and unused Permission remain valid. |
| 595 | |
| 596 | ⛔ **GATE 2 — lock context fidelity.** After Gate 1 closes, author machine-relevant anchors/routing into `spec_lock.md`. The lock may normalize syntax and add justified recurring roles, but must not change identity, discard a refinement, introduce a direction, or become a field copy/allowlist. On contradiction, return to Gate 1 using retained confirmation by default or the approved revised Design Spec after refinement; fresh recovery reads persisted final evidence once only when active state is absent. |
| 597 | |
| 598 | **Execution lock content**: `spec_lock.md` compactly carries communication, stable color/type anchors, icons, images, page rhythm, Chart/Table references, and route-specific PowerPoint structure; qualitative relationships stay only in §IX. Name every recurring typography role; a planned short non-structural Hero/Display size may stay omitted only while the same value appears at most twice, and its third occurrence requires a named role. Never re-derive a confirmed anchor. New locks keep `font_family` as the body/default compatibility stack and also write explicit `title_family` + `body_family`; every additional recurring Design Spec role projects to `<role>_family`. Collapsing distinct Design Spec stacks into `font_family`, or dropping an extra role, fails Gate 2. Keep core fonts/palette roles stable; page authoring varies treatment and may add sparse local garnish. Project every placed §VIII image's source, layout suggestion, and crop policy; omit unplaced sheets and planning provenance. Free-design, brand-only, and `template_reuse_scope: style` use `pptx_structure.mode: flat`; the template module owns structured mappings. Executor context policy lives in [executor-base.md](executor-base.md) §2.1. Repair from Gate 2's active decision authority, then re-author affected lock rows. |
| 599 | |
| 600 | **Contextual extension**: derived paint or sparse local font/color garnish may stay in one SVG while non-structural and non-recurring. New base/semantic colors, structural/recurring fonts, resources, or recurring cross-page identity patterns require upstream repair; a page-local §VIII preferred image pattern follows [`executor-image.md`](./executor-image.md) and may change during realization. Executor never reverse-projects a local choice as planning fact. Promote recurring garnish upstream before reuse, read back and validate the affected planning fragments, and never add values to silence a comparison. |
| 601 | |
| 602 | - **Communication trace is mandatory**: Keep the full confirmed communication contract in `design_spec.md §I`, then project only `audience`, `objective`, `core_message`, and canonical `consumption_mode` into `spec_lock.md communication`. Write `objective` as one concise execution sentence that preserves both the confirmed `communication_intent` and the success condition in `audience_outcome`; do not copy `delivery_context`, `artifact_afterlife`, dates, provenance, or conflict-resolution commentary into the lock. Before finalizing §IX, check that every named purpose has at least one outline obligation and **every Slide block**, including cover / divider / closing pages, has an `Audience move` that advances the global outcome. A page that advances no purpose or outcome should be merged, rewritten, or cut. `project_manager.py validate` and `svg_quality_checker.py` enforce the compact lock fields and per-page move presence, not their subjective quality. |
| 603 | - **Custom behavior is concise and executable**: For confirmed `custom` mode or visual style, project one resolved `mode_behavior` / `visual_style_behavior` sentence or short paragraph. When the direction actually uses catalog entries, also project the exact, comma-separated `mode_references` / `visual_style_references`; omit the field when it uses none and never fabricate a nearby reference. Preserve the confirmed direction, reference locked role names such as `colors.primary` when needed, and omit selection history, contradictions, precedence explanations, or other Design Spec provenance. Executor reads these fields from the retained lock and loads every referenced catalog entry once per valid context. |
| 604 | - **page_rhythm is mandatory**: Based on the page list in §IX Content Outline, assign each page one of `anchor` / `dense` / `breathing`. This is what breaks the uniform "every page is a card grid" feel. New locks may not omit the section; consumer omission behavior is owned by [`executor-base.md`](executor-base.md) §2.1. |
| 605 | - **Fact IDs and scenario labels are mandatory when applicable**: Read any `sources/*.facts.json`. For each §IX page, list the stable IDs actually used; never cite an ID whose claim is absent from the page. Mark invented KPIs/targets/internal ratios as `Data class: scenario` and state which values are scenario data. Executor carries external sources into notes/footnotes and renders a visible scenario label for scenario figures. |
| 606 | - **Mandatory — whole-roster rhythm check**: During the same §IX composition, compare neighbors and section arcs to judge whether chapter entries visibly reset, extended same-density runs are intentional, extended same-carrier or same-topology runs form an intentional semantic sub-arc, repeated dominant geometry carries a continuity job, any qualifying §6.1 visible-state sequence preserves a recognizable mental map while making its next semantic change legible, each section follows a mode-fitting progression—including framework → explanation/evidence → judgment/action when it serves the objective—and the final arc resolves the communication objective before a genuine ending lowers information load. Same section, equal weight or density, one style, and prior-page precedent do not establish a semantic sub-arc. Repair the existing roster, `Layout` recommendations, and `page_rhythm` choices in place. This is judgment, not quota; preserve intentional continuity, legitimately all-`dense` material, and 1:1/literal order. Do not invent filler pages to manufacture rhythm; a `breathing` page marks a meaningful pause—chapter transition, standalone emphasis, or SCQA bridge—and must stand alone. Create no field, lock row, artifact, or second review/execution pass. |
| 607 | - **Cover impact is mandatory**: In `design_spec.md §IX`, give `P01` one concrete hook from the source's strongest claim, metaphor, number, moment, or conflict plus a recommended composition. The hook binds; Executor may adopt, adapt, or decline the composition while preserving the hook and explicit constraints. With no suitable image, recommend a native-SVG hook instead of a generic title treatment. Beautify / template-fill preservation paths are exempt. |
| 608 | - **Cover rhythm lock**: `P01` remains `anchor`. Default away from generic content-page templates; a card grid, agenda, or equal-weight columns remains valid when content, user direction, or the template makes it the clearest cover. |
| 609 | - **Closing impact (only when the deck closes)**: For a genuine conclusion / CTA / final takeaway, name the binding takeaway plus a recommended composition; Executor may adopt, adapt, or decline the latter while preserving the takeaway and explicit constraints. Do not default to an information-empty "Thank you", contact-only slide, or cover reprise; an explicit contact/event CTA may serve the purpose. **Do NOT invent a closing page to satisfy this**. Preservation paths are exempt. |
| 610 | - **pptx_structure is mandatory**: Free-design, brand-only, and `template_reuse_scope: style` routes write `mode: flat`; a style-reference route may also record `template_reuse_scope: style` but omits every structure mapping and `template_adherence`. `template_reuse_scope: mirror|layout` writes `mode: structured` plus `template_adherence: strict|adaptive`. Do not write legacy `baseline`, `template`, `preserve`, `layout_strategy`, or Layout-kind rows into a new project. |
| 611 | - **Flat-route boundary**: With `mode: flat`, omit `pptx_masters`, `pptx_layouts`, `page_pptx_layouts`, and `page_layouts`. Do not plan native Master/Layout families or reusable placeholder slots. Every generated SVG object remains Slide-local: omit root Master/Layout identity, `data-pptx-layer`, and `data-pptx-placeholder*` metadata. Export materializes one clean project-owned Master plus one Blank Layout from the current color/typography lock, removes stock content placeholders/Layout inventory, and retains only the standard date/footer/slide-number capability hooks. |
| 612 | - **Structured template route**: When [`strategist-template.md`](./strategist-template.md) is active and reuse is `mirror|layout`, follow its complete Master/Layout/slot/prototype mapping rules. |
| 613 | - **page_visualizations**: project at most one §VII `P<NN>: <chart|table>/<key>` per page. Usage/children/qualitative relationships stay in the Design Spec; omit empty/no-match. It locks no geometry/native output. New locks never write legacy `page_charts`. |
| 614 | |
| 615 | --- |
| 616 | |
| 617 | ## 7. Project Boundary |
| 618 | |
| 619 | The Generate route owns project initialization and supplies `<project_path>`. Strategist writes only the two complete planning artifacts at that root plus the explicitly triggered resource manifests; it does not choose or create another project path. |
| 620 | |
| 621 | --- |
| 622 | |
| 623 | ## 8. Handoff |
| 624 | |
| 625 | After validation, return to the Generate Step 4 checkpoint. The route—not this role—owns whether Step 5 runs and how execution resumes or auto-proceeds. |
| 626 |