# outputs/ — repeatable PPTX & PDF generation

This directory holds the **generation pipeline** for two output artifacts derived from the plan markdown source:

1. A **mixed-stakeholder PowerPoint** (16 slides) — [`generated/plan-presentation.pptx`](generated/)
2. A **long-form PDF** of the authoritative plan content — [`generated/plan-longform.pdf`](generated/)

Outputs are regenerated on demand from the current markdown source. Repeatability is anchored by **spec files** (this directory), not by prompts. See [`DESIGN.md`](DESIGN.md) for the full design rationale.

## What lives here

| File / directory | Role |
|---|---|
| [`README.md`](README.md) | This file — entry point, trigger phrases, regeneration procedure. |
| [`DESIGN.md`](DESIGN.md) | Design document for the generation pipeline. Read this once; edit when the approach changes. |
| [`presentation-spec.md`](presentation-spec.md) | **Structure anchor** for the PPTX. Enumerates every slide, its source, and how to populate. Edit this when the deck's shape needs to change. |
| [`longform-spec.md`](longform-spec.md) | **Structure anchor** for the PDF. Chapter/appendix ordering, transformation rules, page setup. Edit this when the PDF's shape needs to change. |
| [`run-log.md`](run-log.md) | Append-only audit log — one entry per regeneration. Created on first run. |
| [`diagrams/`](diagrams/) | Hand-drawn diagram sources (`.mmd`) and exported images (`.png`). Committed source; regeneration embeds the existing PNG verbatim and does not re-render. |
| [`generated/`](generated/) | The actual PPTX and PDF artifacts. Disposable — regenerated from scratch on every run. Do not hand-edit. |

## Trigger phrases

In any Claude Code session (this one or a future one), ask for a regeneration with one of:

- `regenerate outputs` — regenerates both the PPTX and the PDF.
- `regenerate presentation` — PPTX only.
- `regenerate longform` — PDF only.

These phrases are the documented trigger. They map onto the procedure below. Prompts that paraphrase them loosely will still work but lose the "same phrase every time" determinism. Prefer the exact phrase.

## Regeneration procedure

The fixed checklist any Claude session follows when triggered. This is what makes regeneration repeatable — every run reads the same inputs in the same order and produces outputs from them.

1. **Read the relevant spec file.**
   - For PPTX: [`presentation-spec.md`](presentation-spec.md).
   - For PDF: [`longform-spec.md`](longform-spec.md).
   - The spec file is the **structure anchor** — it says exactly what slides / chapters exist and what source feeds each one.

2. **Read every source file named in the spec.** Do **not** read other files in the repo. If a source file is not referenced by the spec, it is not part of the output. This is the rule that prevents drift when new plan files are added — new content only appears in outputs when the spec is updated to reference it.

3. **For each slide / chapter, populate content from the named source using the spec's rules.** Rules are per-entry and may say: quote verbatim, summarize to N bullets max, embed the diagram image at path X, render as a table with these columns, etc. When the spec says N bullets, use N bullets — no fewer, no more.

4. **Invoke the rendering skill.**
   - For PPTX: `document-skills:pptx` with the theme and layout from the spec.
   - For PDF: `document-skills:pdf` with the page setup and transformation rules from the spec.
   - Output goes to [`generated/plan-presentation.pptx`](generated/) or [`generated/plan-longform.pdf`](generated/).

5. **Append a run log entry** to [`run-log.md`](run-log.md) with:
   - Timestamp
   - What was regenerated
   - Any warnings: truncations, missing sections, unresolved inter-file links, missing diagram images, anything unexpected in the source
   - A one-line summary of the source plan state ("3 legacy integrations, 6 protocol survey rows, no new source files since last run") so drift is detectable by diffing the log

## Edit-this-not-that rules

| If you want to change... | Edit this | Do NOT edit this |
|---|---|---|
| What goes on slide 7 | `presentation-spec.md` | `current-state.md` |
| The order of chapters in the PDF | `longform-spec.md` | the source files |
| A typo in the plan | The source markdown file (`current-state.md`, `goal-state.md`, etc.) | The spec files |
| The architecture diagram | `diagrams/architecture-layers.mmd` (and re-render to PNG) | the generated `.pptx` |
| The deck's theme / visual style | `presentation-spec.md` (meta header section) | the generated `.pptx` |
| The PDF's page setup | `longform-spec.md` (meta header section) | the generated `.pdf` |
| Anything in `generated/` | — | Don't. Files there are regenerated from scratch. Edit the spec or source instead. |

**The golden rule:** if it's in `generated/`, it's disposable. If it's anywhere else in `outputs/`, it's committed source and hand-edits stick. If it's a plan markdown file, it's the authoritative source of truth and the spec files consume it, not the other way around.

## Diagrams

Diagrams are **hand-drawn source files** committed to [`diagrams/`](diagrams/), not generated fresh on each run. This is deliberate — the single biggest drift vector in LLM-driven generation is "Claude redraws the diagram each run and it looks slightly different every time."

- The source is a Mermaid `.mmd` text file — diffable, editable, renderable at [https://mermaid.live](https://mermaid.live).
- The render is a `.png` committed alongside the `.mmd`.
- Regeneration embeds the existing `.png` verbatim. Zero drift between runs as long as nobody edits the `.mmd`.

**When a diagram needs to change:**

1. Edit the `.mmd` file (or ask Claude to rewrite it).
2. Re-render the PNG — either Claude does it in-session if Mermaid tooling is available, or you render it manually at https://mermaid.live and save the PNG into `diagrams/`.
3. Run `regenerate presentation`. The new PNG is picked up automatically.

## Starter diagram set

The spec currently references two diagrams:

- `diagrams/architecture-layers.png` — the 4-layer goal-state architecture stack (Equipment → OtOpcUa → SCADA → ScadaBridge → Enterprise IT), with the IT↔OT boundary marked.
- `diagrams/end-to-end-flow.png` — the left-to-right data flow for one tag (Equipment → OtOpcUa → System Platform/Ignition → ScadaBridge → Redpanda → SnowBridge → Snowflake → Power BI). SnowBridge owns ingest + in-process transform; no separate dbt hop.

Both are **not yet authored.** On first regeneration, Claude will either author the `.mmd` sources and attempt to render them, or flag this as a manual step in the run log. Until the PNGs exist, the corresponding slides (slides 8 and 9 in the deck) will have placeholder boxes.

A third diagram (`roadmap-timeline`) is **intentionally not part of the starter set** — the roadmap renders as a PPTX table on slide 13, and a Gantt-style diagram would compete with the grid rather than complement it. Add later if the table feels flat.

## What this pipeline does NOT do

- **No auto-regeneration.** Outputs are regenerated only when explicitly triggered. This avoids producing stale-looking artifacts between meaningful plan updates.
- **No source-file edits.** Regeneration is read-only on the plan markdown. The only writes are to `generated/` and `run-log.md`.
- **No diagram re-rendering on each run.** Diagrams are embedded verbatim from committed PNGs — see the Diagrams section above.
- **No second theme.** First pass uses `document-skills:theme-factory` default professional. Branding and custom themes are a follow-up iteration.
- **No curated narrative PDF.** First pass is a faithful typeset of the source markdown (option (a) from the design brainstorm). A reshaped, executive-narrative PDF is a potential second output.
- **No slash command.** A `.claude/commands/regenerate-outputs.md` slash command was considered and deferred — the plain English trigger + this README's checklist is enough for the first pass.

## Related files

- [`../CLAUDE.md`](../CLAUDE.md) — plan structure and conventions
- [`../current-state.md`](../current-state.md), [`../goal-state.md`](../goal-state.md), [`../roadmap.md`](../roadmap.md) — the authoritative plan
- [`../status.md`](../status.md) — working bookmark, NOT part of the generated outputs
- [`DESIGN.md`](DESIGN.md) — full design document for this pipeline
- [`IMPLEMENTATION-PLAN.md`](IMPLEMENTATION-PLAN.md) — the scaffolding plan (partially executed; see its status section)
