3yearplan/outputs

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 (18 slides) — generated/plan-presentation.pptx
2. A long-form PDF of the authoritative plan content — generated/plan-longform.pdf

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

What lives here

File / directory	Role
README.md	This file — entry point, trigger phrases, regeneration procedure.
DESIGN.md	Design document for the generation pipeline. Read this once; edit when the approach changes.
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	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	Append-only audit log — one entry per regeneration. Created on first run.
diagrams/	Hand-drawn diagram sources (.mmd) and exported images (.png). Committed source; regeneration embeds the existing PNG verbatim and does not re-render.
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.
   • For PDF: 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 or generated/plan-longform.pdf.

5. Append a run log entry to 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/, 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.
• 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, matching goal-state.md line 77 exactly (Equipment → OtOpcUa → System Platform/Ignition → ScadaBridge → Redpanda → SnowBridge → Snowflake → dbt → Power BI).

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 — plan structure and conventions
• ../current-state.md, ../goal-state.md, ../roadmap.md — the authoritative plan
• ../status.md — working bookmark, NOT part of the generated outputs
• DESIGN.md — full design document for this pipeline
• IMPLEMENTATION-PLAN.md — the scaffolding plan (partially executed; see its status section)