| 1 | # Reference Document Style Guide |
| 2 | |
| 3 | > Style rules for files under `skills/ppt-master/references/`. Follow these when writing or reviewing role definitions and shared specs. |
| 4 | |
| 5 | The reference layer drives runtime LLM behavior. Style consistency across these files matters as much as correctness — divergent voice / structure forces the model to re-interpret each file from scratch and bloats the loaded context. |
| 6 | |
| 7 | --- |
| 8 | |
| 9 | ## 1. Document Header |
| 10 | |
| 11 | | Element | Rule | |
| 12 | |---|---| |
| 13 | | Top line | `> See [`xxx`](xxx.md) for ...` — one-line cross-reference, optional | |
| 14 | | H1 title | `# Role: X` (for role files) or `# X Reference Manual` / `# X Specification` | |
| 15 | | Opening paragraph | One sentence stating mission + trigger. Max 2 lines | |
| 16 | | `## Core Mission` | Optional; if present, ≤ 3 sentences | |
| 17 | |
| 18 | ✅ Good (from `image-searcher.md`): |
| 19 | ``` |
| 20 | > See [`image-base.md`](./image-base.md) for the common framework. |
| 21 | |
| 22 | # Image_Searcher Reference Manual |
| 23 | |
| 24 | Role definition for the **web image acquisition path**: translate Strategist intent into keyword queries, search openly-licensed providers, download a license-cleared image into `project/images/`, and record provenance + license metadata into `image_sources.json`. |
| 25 | |
| 26 | **Trigger**: resource list rows with `Acquire Via: web`. The role is loaded only when at least one such row exists. |
| 27 | ``` |
| 28 | |
| 29 | ❌ Avoid: long "Core Mission" paragraphs that explain *why* the role exists, list its philosophical goals, or narrate the pipeline context. |
| 30 | |
| 31 | --- |
| 32 | |
| 33 | ## 2. Sectioning |
| 34 | |
| 35 | | Level | Format | Notes | |
| 36 | |---|---|---| |
| 37 | | Main | `## N. Title` | Numbered from 1 | |
| 38 | | Sub | `### N.1` / `### N.2` ... | Or `### a.` / `### b.` for confirmation flows | |
| 39 | | Divider | `---` between main sections | Always | |
| 40 | |
| 41 | `## Core Mission`, `## Pipeline Context`, `## Trigger` may appear before `## 1.` without numbering. |
| 42 | |
| 43 | --- |
| 44 | |
| 45 | ## 3. Voice — Command, Not Explanation |
| 46 | |
| 47 | | Use | Don't use | |
| 48 | |---|---| |
| 49 | | `Run X.` | `You should typically run X because ...` | |
| 50 | | `Output: Y` | `The role outputs Y, which is important because ...` | |
| 51 | | `MUST come from Z` | `It is recommended to source from Z` | |
| 52 | | `Forbidden — unresolved image references` | `Anti-pattern: broken image links` | |
| 53 | |
| 54 | **Hard rule — retain failure predicates**: Cut narrative teaching and background motivation. Keep one compact protected invariant or failure predicate when it determines the rule's strength, scope, or safe generalization; attach it to the rule or one `> Note` line. Runtime prompts need the behavior and its objective failure boundary, not the full rationale. |
| 55 | |
| 56 | --- |
| 57 | |
| 58 | ## 4. Bold Inline Labels |
| 59 | |
| 60 | Begin substantive paragraphs with a bolded short label. Reuse this fixed vocabulary: |
| 61 | |
| 62 | | Label | Use for | |
| 63 | |---|---| |
| 64 | | `**Hard rule**:` | Non-negotiable behavior | |
| 65 | | `**Forbidden — xxx**:` | Disallowed values / actions, followed by a list | |
| 66 | | `**Mandatory**:` | Required step within an optional phase | |
| 67 | | `**Default — X (may override when …)**:` | A sensible default that saves re-deciding; deviating is allowed with a stated reason | |
| 68 | | `**Reference — not a constraint**:` | Vocabulary or options with no single right answer — a recall aid, not an instruction (replaces scattered "for recall, not constraint" / "illustrative only") | |
| 69 | | `**When to run**:` / `**Trigger**:` | Activation condition | |
| 70 | | `**Validation**:` | Post-step assertion | |
| 71 | | `**Per-page xxx**:` / `**Per-row xxx**:` | Loop body description | |
| 72 | | `**Generation pacing (mandatory)**:` | Concurrency / rate constraint | |
| 73 | | `**Missing X**` → ... | Fallback behavior | |
| 74 | |
| 75 | ✅ Good (from `executor-base.md`): |
| 76 | ``` |
| 77 | **Hard rule**: Reuse the complete Design Spec and lock while the active context remains valid. After compaction or fresh/resumed execution, read both once before continuing. |
| 78 | |
| 79 | **Forbidden — unresolved asset references**: |
| 80 | - Icons MUST resolve to prepared project-local assets |
| 81 | - Images MUST resolve to declared project assets |
| 82 | ``` |
| 83 | |
| 84 | **Choosing the strength** — before labeling a constraint, ask: *if a page violates it, does it objectively fail (text overlaps, overflows, misaligns, becomes unreadable, loses information, breaks across renderers), or could it merely look worse?* |
| 85 | |
| 86 | | Answer | Label | |
| 87 | |---|---| |
| 88 | | Objective failure, checkable by a concrete trigger | `**Hard rule**:` / `**Forbidden**:` | |
| 89 | | Has a sensible default, deviation can be justified | `**Default — … (may override)**:` | |
| 90 | | No right answer — taste, style, or scenario fit | `**Reference — not a constraint**:` | |
| 91 | |
| 92 | Boundary cases go by this test, not by how strong the verb feels: "never split a full sentence into bullets" stays near-MUST because splitting *loses the information that the block was continuous reasoning*, not because "never" sounds strict. |
| 93 | |
| 94 | **Hard rule**: A `Hard rule` or `Forbidden` label whose failure boundary is not self-evident retains one compact objective predicate. If no objective predicate exists, demote the instruction to `Default` or `Reference` instead of preserving only a strong verb. |
| 95 | |
| 96 | > Note: only a MUST with a concrete objective trigger may become a `svg_quality_checker.py` rule. SHOULD is at most a `warning`; MAY is never checked — encoding taste as a check turns the checker into a de-facto spec. |
| 97 | |
| 98 | ### 4.1 Ownership Contract: Ingredients → Plan + Preparation → Realization |
| 99 | |
| 100 | Constraint strength and decision ownership are independent. Preserve this chain whenever writing, compressing, or reviewing the default multi-role Generate prompts: |
| 101 | |
| 102 | | Layer | Owns | |
| 103 | |---|---| |
| 104 | | User / initial materials | Supplied facts/assets, desired outcome, exclusions, and permission boundaries remain authoritative | |
| 105 | | Strategist / plan + preparation | Assess material sufficiency; trigger permitted topic research and retain its research/provenance pair without expanding adopted webpage URLs; decide the approved content, resources, keys, identity anchors, and exact page roster. During that roster composition, resolve each page's semantic carrier mix—background, text/lettering, native-geometry/relationship jobs, imagery/symbols, and data carriers—in one pass before deriving external-resource rows. Recommend high-level composition, visual focus, and continuity as Reference when useful, without selecting a local authoring capability or element geometry; materialize the planned project-local inventory or record an explicit `Needs-Manual` dependency before execution. For icons, prepare a curated project pool with broad semantic fit rather than assigning files to pages | |
| 106 | | Executor / realization | Use only prepared project-local assets; preserve approved content, resources, and identity anchors; realize each page by resolving the actual carrier combination, geometry, composition, hierarchy, and treatment together before coordinates. Discover and invoke local deterministic authoring capabilities without an upstream capability selection. Consider each field explicitly labeled `suggestion` or Reference, then adopt, adapt, or decline it while preserving its semantic job and every binding constraint. For icons, the complete `<project>/icons/` pool is prepared material; `icons.inventory` is a curated bundled-pool index, not a page-use plan or whitelist, and Executor chooses prepared icons per page without a coverage quota. Sparse local font/color garnish is allowed only while non-structural and non-recurring | |
| 107 | |
| 108 | **Hard rule — capability knowledge precedes selection**: physical file |
| 109 | boundaries do not imply runtime lazy-loading. A role loads the complete decision |
| 110 | authorities for every capability it owns before choosing among those |
| 111 | capabilities; otherwise the load trigger circularly depends on a choice made |
| 112 | without that capability. Default Strategist's fixed planning bundle covers |
| 113 | resource/preparation and high-level expression options without local authoring |
| 114 | parameters. Executor's fixed construction bundle covers locally callable |
| 115 | authoring options. Quick loads both decision surfaces in its one context. Only |
| 116 | post-selection mechanics whose trigger is independently observable may remain |
| 117 | conditional. For example, an actual `ai` / `slice` resource row may trigger |
| 118 | Image_Generator backend, prompt-assembly, and per-image type details after |
| 119 | planning; those mechanics are not a missing Strategist capability. |
| 120 | |
| 121 | **Hard rule — native shapes are authoring capabilities, not prepared |
| 122 | resources**: a prepared resource needs a stable project-local file/path before |
| 123 | realization because page authoring cannot acquire or generate it in place. |
| 124 | Office presets, SVG primitives, Connectors, Boolean helpers, and necessary |
| 125 | freeform geometry are locally callable construction capabilities. Strategist |
| 126 | never inventories them or promotes a concrete preset, primitive, Connector, |
| 127 | Boolean/freeform operation, or authoring parameter into a binding planning |
| 128 | selection. A macro Reference may mention a technique as optional inspiration |
| 129 | without prescribing or gating construction. The Design Spec / lock create no |
| 130 | native-shape field; Executor reads the complete current preset vocabulary and |
| 131 | chooses the page-fit construction during realization. |
| 132 | |
| 133 | **Preparation timing**: In the default pipeline, topic research and import of |
| 134 | its two-artifact research pair may run before final confirmation. Facts JSON |
| 135 | URLs are not auto-expanded. AI / web / slice acquisition runs only from the |
| 136 | completed `design_spec.md §VIII` and `spec_lock.md`, after final confirmation |
| 137 | and before Executor. Only after normal image search fails may one relevant |
| 138 | adopted page become a Markdown + companion-image source package; review it and |
| 139 | promote accepted files individually, never the whole package. Image_Generator, |
| 140 | Image_Searcher, and icon-sync tooling execute Strategist-owned preparation; |
| 141 | they are not independent decision owners. |
| 142 | |
| 143 | **Post-motion sound exception**: optional transition/object sound is not a |
| 144 | page-authoring ingredient and never enters Strategist planning, |
| 145 | `design_spec.md`, or `spec_lock.md`. After the SVG roster and visual motion |
| 146 | solution are complete, the active animation/export stage may discover bundled |
| 147 | sound ids and sync only a concretely selected cue into the project. With no |
| 148 | selected cue, it creates no `<project>/sounds/` directory. This exception does |
| 149 | not permit Executor to acquire visual resources. |
| 150 | |
| 151 | **Hard rule — default pipeline**: downstream freedom exists only in dimensions left open upstream, including fields explicitly labeled `suggestion` or Reference. A named binding outcome retains identity; a broad semantic request or expression recommendation permits in-class choice. Executor may adopt, adapt, or decline a Reference without upstream repair unless an explicit user/template/resource constraint promotes the named property. Once the plan resolves a binding choice, execution cannot reopen or substitute it. For icons, library/stroke and the prepared-project boundary bind, while per-page choice within the prepared pool is realization. Executor never searches, generates, downloads, syncs, invents, or replaces a resource; missing material returns to Strategist-owned preparation or upstream repair. |
| 152 | |
| 153 | **Explicit Quick Generate exception**: [`quick-generate`](../../skills/ppt-master/workflows/profiles/quick-generate.md) removes the separate Strategist/confirmation handoff. The current main agent therefore owns both its active-context decisions and the preparation of project-local sources, images, icons, and provenance before it begins SVG realization; native formulas are authored directly from exact mathematical content rather than acquired as resources. This exception does not move acquisition into a default-pipeline Executor and does not permit resource reselection while a page is being realized. Explicit user facts, choices, exclusions, and permissions remain upstream authority; unspecified routine choices are resolved automatically without a confirmation stop. |
| 154 | |
| 155 | > Mnemonic — restaurant contract: the customer supplies initial ingredients and the desired dish; Strategist plans the dish and prepares the complete mise en place; Executor cooks from that prepared inventory. “Mapo tofu” cannot become tomato-and-eggs or tofu soup, while “a tofu dish” leaves deliberate in-class freedom. |
| 156 | |
| 157 | **Review gate**: treat any prompt refactor that erases the selected profile's ownership chain, moves acquisition into the default-pipeline Executor, turns a permission into a quota, or turns flexible realization into silent resource/identity reselection as a semantic regression even when the compressed wording is shorter. |
| 158 | |
| 159 | --- |
| 160 | |
| 161 | ## 5. Tables First |
| 162 | |
| 163 | Most sections need at least one table. Reach for a table whenever you would write 3+ parallel bullet points. |
| 164 | |
| 165 | | Use case | Format | |
| 166 | |---|---| |
| 167 | | Enums, modes, options | Table with `Key | Behavior` | |
| 168 | | Field definitions | Table with `Field | Notes` | |
| 169 | | Decision matrices | Table with `Condition | Action` | |
| 170 | | Cross-reference index | Table with `Term | Defined in` | |
| 171 | |
| 172 | Bullets are fine for ≤ 3 short imperatives or a single ordered procedure. |
| 173 | |
| 174 | ### 5.1 Closed vs Illustrative Lists |
| 175 | |
| 176 | Strength (§4) and extent are separate axes: a `Hard rule` may carry an illustrative list, and a `Reference` may carry a closed one. |
| 177 | |
| 178 | | List kind | Test | Marking | |
| 179 | |---|---|---| |
| 180 | | Closed | A schema, validator, exporter, or script rejects an unlisted value | State the complete set; adding a value means changing that consumer too | |
| 181 | | Illustrative | The list names instances of a broader idea the reader must still judge | Say so inline — `common triggers rather than an exhaustive list` | |
| 182 | |
| 183 | ❌ An unmarked enumeration reads as closed, the same way an unlabeled soft rule reads as hard (§11). |
| 184 | |
| 185 | ❌ Never phrase a rule so it turns an illustrative list into a lookup obligation. "Consult `<table>` for `<X>`" makes that table's rows the only reachable answers and invites restating `<X>` until it matches one — even when the table's own boundary grants free-form authorship. Point at the procedure that generates answers; offer the table as a shortcut when an entry already matches. |
| 186 | |
| 187 | --- |
| 188 | |
| 189 | ## 6. Examples |
| 190 | |
| 191 | | Form | Use | |
| 192 | |---|---| |
| 193 | | Fenced code block (` ``` `) | Commands, file content, ASCII diagrams | |
| 194 | | Inline code (` ` `) | File paths, identifiers, env vars | |
| 195 | | 2-column ✅/❌ table | Short keyword-vs-keyword contrast (one phrase per cell) | |
| 196 | |
| 197 | ❌ Avoid: 3-column ✅/❌/(why) tables. The "why" column is explanation — drop it or move to a `>` note. |
| 198 | |
| 199 | ❌ Avoid: long narrative example paragraphs. Use a code block or table. |
| 200 | |
| 201 | --- |
| 202 | |
| 203 | ## 7. Forbidden Section Types |
| 204 | |
| 205 | These section names are not used anywhere in `references/`. Do not introduce them: |
| 206 | |
| 207 | - `## Anti-patterns` |
| 208 | - `## Best Practices` |
| 209 | - `## Tips` |
| 210 | - `## FAQ` (FAQ lives in `docs/faq.md`) |
| 211 | - `## Why X` |
| 212 | - `## Background` / `## Motivation` |
| 213 | |
| 214 | If you have rules to communicate that would naturally land in one of these sections, integrate them into the relevant numbered section as a `**Forbidden — xxx**` block or a `> Note` line. |
| 215 | |
| 216 | --- |
| 217 | |
| 218 | ## 8. Cross-References |
| 219 | |
| 220 | | Reference type | Format | |
| 221 | |---|---| |
| 222 | | Sibling reference file | `[`xxx`](./xxx.md)` | |
| 223 | | Section in same file | `§N.M` (no link) | |
| 224 | | Section in another file | `[`xxx`](./xxx.md) §N.M` | |
| 225 | | Script doc | `[`xxx`](../scripts/docs/xxx.md)` | |
| 226 | | Workflow | `[`xxx`](../workflows/xxx.md)` | |
| 227 | |
| 228 | Always backtick-wrap the filename in the link text. |
| 229 | |
| 230 | --- |
| 231 | |
| 232 | ## 9. Annotations |
| 233 | |
| 234 | | Symbol | Meaning | |
| 235 | |---|---| |
| 236 | | `🚧 **GATE**:` | Mandatory checkpoint before proceeding | |
| 237 | | `⛔ **BLOCKING**:` | Must wait for explicit user confirmation | |
| 238 | | `📝 **Template mapping**:` | Page-to-template declaration (Executor-specific) | |
| 239 | | `> Note` blockquote | Edge case, fallback, or single-line context | |
| 240 | |
| 241 | Use sparingly. If every paragraph has a symbol, none of them carry weight. |
| 242 | |
| 243 | --- |
| 244 | |
| 245 | ## 10. Checkpoint Output Format |
| 246 | |
| 247 | Each phase ends with a fenced markdown block showing the agent's expected completion confirmation: |
| 248 | |
| 249 | ````markdown |
| 250 | ## ✅ {Phase Name} Complete |
| 251 | |
| 252 | - [x] {evidence-driven assertion 1} |
| 253 | - [x] {evidence-driven assertion 2} |
| 254 | - [ ] **Next**: {next-phase pointer} |
| 255 | ```` |
| 256 | |
| 257 | Items are evidence-driven (`file exists at path X`, `status N is Generated`), not aspirational (`prompts are good`). |
| 258 | |
| 259 | --- |
| 260 | |
| 261 | ## 11. Forbidden Patterns Across the Whole Layer |
| 262 | |
| 263 | - Localized warning/exclamation blockquotes (use `> Note` or omit) |
| 264 | - Emoji as decoration in headings (✅ in checkpoint headings is the only sanctioned use) |
| 265 | - Smiley face / sparkle / fire emoji |
| 266 | - Footnotes (`[^1]`) |
| 267 | - HTML in markdown body (`<details>`, `<br>`, etc.) — only the SVG embedding examples use real `<svg>`/`<image>` in code blocks, never as live markdown |
| 268 | - "**Best practice**: ..." labels — pick the right strength label instead (§4): `**Hard rule**:` if violating it fails, `**Default — … (may override)**:` if it's a sensible default, `**Reference — not a constraint**:` if it's taste. Never leave a soft suggestion unlabeled — an unlabeled line reads as a hard rule to the model |
| 269 | |
| 270 | --- |
| 271 | |
| 272 | ## 12. When This Guide Conflicts With Existing Files |
| 273 | |
| 274 | Existing files take precedence as ground truth. If a current `references/*.md` violates a rule here, decide whether to (a) update this guide to match the de facto convention, or (b) refactor that file. Don't silently apply a divergent style to one new file. |
| 275 | |
| 276 | The canonical exemplars to model new files after: |
| 277 | |
| 278 | | If you're writing... | Model after | |
| 279 | |---|---| |
| 280 | | A role reference (Image_X / Strategist-style) | [`image-searcher.md`](../../skills/ppt-master/references/image-searcher.md), [`strategist.md`](../../skills/ppt-master/references/strategist.md) | |
| 281 | | A shared spec across roles | [`image-base.md`](../../skills/ppt-master/references/image-base.md), [`shared-standards-core.md`](../../skills/ppt-master/references/shared-standards-core.md) | |
| 282 | | A technical / format spec | [`canvas-formats.md`](../../skills/ppt-master/references/canvas-formats.md), [`svg-image-embedding.md`](../../skills/ppt-master/references/svg-image-embedding.md), [`image-layout-spec.md`](../../skills/ppt-master/references/image-layout-spec.md) | |
| 283 | | Stage runbook | [`workflows/stages/verify-charts.md`](../../skills/ppt-master/workflows/stages/verify-charts.md) | |
| 284 | |
| 285 | --- |
| 286 | |
| 287 | ## 13. Prompt Refactor Review |
| 288 | |
| 289 | Prompt compression is complete only after reviewing token reduction and semantic change separately. |
| 290 | |
| 291 | | Check | Required evidence | |
| 292 | |---|---| |
| 293 | | Owner and consumer | Each moved field or capability still has one authority, and every runtime consumer loads or projects that authority | |
| 294 | | Strength delta | Record `before → after` for deleted, moved, or rewritten `Hard rule`, `Forbidden`, `Default`, and `Reference` instructions | |
| 295 | | Failure predicate | Preserve the compact objective invariant that justifies every non-self-evident hard boundary | |
| 296 | | Freedom boundary | A permission did not become a quota, a reference did not become a lock, and flexible realization did not become silent reselection | |
| 297 | | Preparation timing | Strategist-owned acquisition and materialization did not move into Executor or before final confirmation | |
| 298 | | Capability discovery | Conditional deep specifications retain a short visible menu or an externally observable trigger before their load gate | |
| 299 | | Token delta | Report route/file budget changes separately; a budget pass does not prove semantic equivalence | |
| 300 | |
| 301 | **Hard rule**: A shorter prompt that changes decision ownership, constraint strength, preparation timing, or capability discoverability is a semantic regression even when structural and token-budget audits pass. |
| 302 |