| 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 fact research; decide the approved content, resources, keys, identity anchors, and exact page roster; record optional capability/expression recommendations; 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 them through geometry, composition, hierarchy, and treatment. Fields explicitly labeled `suggestion` or Reference are preferred expression rather than binding selections: Executor may adapt or decline them when content and explicit constraints remain intact. 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 | **Preparation timing**: In the default pipeline, fact research required for planning may run before final confirmation. AI / web / slice acquisition runs only from the completed `design_spec.md §VIII` and `spec_lock.md`, after final confirmation and before Executor. Image_Generator, Image_Searcher, and icon-sync tooling execute Strategist-owned preparation; they are not independent decision owners. |
| 109 | |
| 110 | **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. 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. |
| 111 | |
| 112 | **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, formulas, and provenance before it begins SVG realization. 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. |
| 113 | |
| 114 | > 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. |
| 115 | |
| 116 | **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. |
| 117 | |
| 118 | --- |
| 119 | |
| 120 | ## 5. Tables First |
| 121 | |
| 122 | Most sections need at least one table. Reach for a table whenever you would write 3+ parallel bullet points. |
| 123 | |
| 124 | | Use case | Format | |
| 125 | |---|---| |
| 126 | | Enums, modes, options | Table with `Key | Behavior` | |
| 127 | | Field definitions | Table with `Field | Notes` | |
| 128 | | Decision matrices | Table with `Condition | Action` | |
| 129 | | Cross-reference index | Table with `Term | Defined in` | |
| 130 | |
| 131 | Bullets are fine for ≤ 3 short imperatives or a single ordered procedure. |
| 132 | |
| 133 | --- |
| 134 | |
| 135 | ## 6. Examples |
| 136 | |
| 137 | | Form | Use | |
| 138 | |---|---| |
| 139 | | Fenced code block (` ``` `) | Commands, file content, ASCII diagrams | |
| 140 | | Inline code (` ` `) | File paths, identifiers, env vars | |
| 141 | | 2-column ✅/❌ table | Short keyword-vs-keyword contrast (one phrase per cell) | |
| 142 | |
| 143 | ❌ Avoid: 3-column ✅/❌/(why) tables. The "why" column is explanation — drop it or move to a `>` note. |
| 144 | |
| 145 | ❌ Avoid: long narrative example paragraphs. Use a code block or table. |
| 146 | |
| 147 | --- |
| 148 | |
| 149 | ## 7. Forbidden Section Types |
| 150 | |
| 151 | These section names are not used anywhere in `references/`. Do not introduce them: |
| 152 | |
| 153 | - `## Anti-patterns` |
| 154 | - `## Best Practices` |
| 155 | - `## Tips` |
| 156 | - `## FAQ` (FAQ lives in `docs/faq.md`) |
| 157 | - `## Why X` |
| 158 | - `## Background` / `## Motivation` |
| 159 | |
| 160 | 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. |
| 161 | |
| 162 | --- |
| 163 | |
| 164 | ## 8. Cross-References |
| 165 | |
| 166 | | Reference type | Format | |
| 167 | |---|---| |
| 168 | | Sibling reference file | `[`xxx`](./xxx.md)` | |
| 169 | | Section in same file | `§N.M` (no link) | |
| 170 | | Section in another file | `[`xxx`](./xxx.md) §N.M` | |
| 171 | | Script doc | `[`xxx`](../scripts/docs/xxx.md)` | |
| 172 | | Workflow | `[`xxx`](../workflows/xxx.md)` | |
| 173 | |
| 174 | Always backtick-wrap the filename in the link text. |
| 175 | |
| 176 | --- |
| 177 | |
| 178 | ## 9. Annotations |
| 179 | |
| 180 | | Symbol | Meaning | |
| 181 | |---|---| |
| 182 | | `🚧 **GATE**:` | Mandatory checkpoint before proceeding | |
| 183 | | `⛔ **BLOCKING**:` | Must wait for explicit user confirmation | |
| 184 | | `📝 **Template mapping**:` | Page-to-template declaration (Executor-specific) | |
| 185 | | `> Note` blockquote | Edge case, fallback, or single-line context | |
| 186 | |
| 187 | Use sparingly. If every paragraph has a symbol, none of them carry weight. |
| 188 | |
| 189 | --- |
| 190 | |
| 191 | ## 10. Checkpoint Output Format |
| 192 | |
| 193 | Each phase ends with a fenced markdown block showing the agent's expected completion confirmation: |
| 194 | |
| 195 | ````markdown |
| 196 | ## ✅ {Phase Name} Complete |
| 197 | |
| 198 | - [x] {evidence-driven assertion 1} |
| 199 | - [x] {evidence-driven assertion 2} |
| 200 | - [ ] **Next**: {next-phase pointer} |
| 201 | ```` |
| 202 | |
| 203 | Items are evidence-driven (`file exists at path X`, `status N is Generated`), not aspirational (`prompts are good`). |
| 204 | |
| 205 | --- |
| 206 | |
| 207 | ## 11. Forbidden Patterns Across the Whole Layer |
| 208 | |
| 209 | - Localized warning/exclamation blockquotes (use `> Note` or omit) |
| 210 | - Emoji as decoration in headings (✅ in checkpoint headings is the only sanctioned use) |
| 211 | - Smiley face / sparkle / fire emoji |
| 212 | - Footnotes (`[^1]`) |
| 213 | - HTML in markdown body (`<details>`, `<br>`, etc.) — only the SVG embedding examples use real `<svg>`/`<image>` in code blocks, never as live markdown |
| 214 | - "**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 |
| 215 | |
| 216 | --- |
| 217 | |
| 218 | ## 12. When This Guide Conflicts With Existing Files |
| 219 | |
| 220 | 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. |
| 221 | |
| 222 | The canonical exemplars to model new files after: |
| 223 | |
| 224 | | If you're writing... | Model after | |
| 225 | |---|---| |
| 226 | | 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) | |
| 227 | | 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) | |
| 228 | | 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) | |
| 229 | | Stage runbook | [`workflows/stages/verify-charts.md`](../../skills/ppt-master/workflows/stages/verify-charts.md) | |
| 230 | |
| 231 | --- |
| 232 | |
| 233 | ## 13. Prompt Refactor Review |
| 234 | |
| 235 | Prompt compression is complete only after reviewing token reduction and semantic change separately. |
| 236 | |
| 237 | | Check | Required evidence | |
| 238 | |---|---| |
| 239 | | Owner and consumer | Each moved field or capability still has one authority, and every runtime consumer loads or projects that authority | |
| 240 | | Strength delta | Record `before → after` for deleted, moved, or rewritten `Hard rule`, `Forbidden`, `Default`, and `Reference` instructions | |
| 241 | | Failure predicate | Preserve the compact objective invariant that justifies every non-self-evident hard boundary | |
| 242 | | Freedom boundary | A permission did not become a quota, a reference did not become a lock, and flexible realization did not become silent reselection | |
| 243 | | Preparation timing | Strategist-owned acquisition and materialization did not move into Executor or before final confirmation | |
| 244 | | Capability discovery | Conditional deep specifications retain a short visible menu or an externally observable trigger before their load gate | |
| 245 | | Token delta | Report route/file budget changes separately; a budget pass does not prove semantic equivalence | |
| 246 | |
| 247 | **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. |
| 248 |