3yearplan/outputs/DESIGN.md

Design — Repeatable Output Generation

Date: 2026-04-15 Topic: PPTX presentation and PDF longform generation from the 3-year plan markdown source. Status: Approved — proceeding to implementation.

Path note. The superpowers-extended-cc:brainstorming skill's default location for this file is docs/plans/YYYY-MM-DD-<topic>-design.md, but this repo's convention (per ../CLAUDE.md) is markdown files at root or under topical subdirectories. This design document is about the output-generation pipeline, so it lives alongside the pipeline it describes in outputs/. Same intent, different path.

Problem

The plan lives in ~10 markdown files. It needs to be published as:

1. A mixed-stakeholder PowerPoint (18 slides) for steering / leadership / technical-lead audiences.
2. A long-form PDF of the authoritative plan content for archival, handoff, and offline reading.

Both outputs must be repeatable reliably across sessions and across time — regenerating them after the plan has evolved should produce consistent structure and style, with bounded variability in Claude-authored phrasing only.

Approach — four-part reliability harness

Free-form "Claude, regenerate the outputs" drifts. The four fixes:

1. Spec files as structure anchors. outputs/presentation-spec.md and outputs/longform-spec.md enumerate exactly which source feeds which slide / chapter, with no Claude discretion over structure. The prompt ("regenerate outputs") stays constant; the specs evolve as the plan does.
2. Pinned invocation checklist. outputs/README.md documents the trigger phrases and the numbered procedure I follow on every regeneration. No free-form prompting.
3. Hand-drawn diagrams as committed files. outputs/diagrams/*.mmd + outputs/diagrams/*.png. Diagrams change only when the .mmd is edited and re-rendered; regeneration just embeds the existing PNG.
4. Diff-friendly intermediate + run log. Every regeneration appends a line to outputs/run-log.md recording the timestamp, what was regenerated, and any warnings (missing source sections, broken links, overflow truncations). Drift between runs is visible by construction.

Together these reduce "what Claude has to decide" to text phrasing inside a fixed structure, which has bounded variability that the run log makes auditable.

Section 1 — Repo structure

plan/
├── current-state.md, goal-state.md, roadmap.md, status.md    (existing, unchanged)
├── current-state/, goal-state/                                (existing, unchanged)
└── outputs/                                                    (NEW)
    ├── README.md                 — trigger phrases + numbered regeneration checklist
    ├── DESIGN.md                 — this document
    ├── run-log.md                — append-only regeneration audit log
    ├── presentation-spec.md      — slide-by-slide PPTX structure anchor
    ├── longform-spec.md          — chapter/appendix structure anchor
    ├── diagrams/
    │   ├── architecture-layers.mmd      (Mermaid source, committed)
    │   ├── architecture-layers.png      (exported, committed)
    │   ├── end-to-end-flow.mmd
    │   └── end-to-end-flow.png
    └── generated/
        ├── plan-presentation.pptx
        └── plan-longform.pdf

Spec files and diagrams are source; generated/ is artifact.

Section 2 — Generation workflow

Trigger phrases (any future Claude session recognizes these from outputs/README.md):

• regenerate outputs — both
• regenerate presentation — PPTX only
• regenerate longform — PDF only

Procedure (checklist in outputs/README.md):

1. Read outputs/presentation-spec.md or outputs/longform-spec.md — the structure anchor.
2. Read every source file named in the spec. Files not in the spec are not read.
3. For each slide / chapter in the spec, populate from the named source using the spec's rules (full text, N-bullet summary, diagram embed, etc.).
4. Invoke document-skills:pptx or document-skills:pdf to render to outputs/generated/.
5. Append a run log entry to outputs/run-log.md.

Regeneration is read-only on plan content. The only files it writes to are under outputs/generated/ and outputs/run-log.md.

Section 3 — PPTX spec (18 slides, mixed-stakeholder)

Slide-by-slide mapping (full detail lives in outputs/presentation-spec.md):

#	Slide	Source anchor
1	Title	—
2	Executive Summary	goal-state.md → Vision + Success Criteria
3	Today's Reality	current-state.md → pain points
4	Vision	goal-state.md → Vision
5	Three Pillars	goal-state.md → Success Criteria
6	Enterprise Layout	current-state.md → Enterprise Layout
7	Today's Systems	current-state.md → Systems & Interfaces
8	Architecture (diagram)	goal-state.md → Layered Architecture + diagrams/architecture-layers.png
9	Data Flow (diagram)	goal-state.md → tag flow sentence + diagrams/end-to-end-flow.png
10	OtOpcUa	goal-state.md → OtOpcUa
11	Analytics Stack	goal-state.md → SnowBridge + Historian→Snowflake
12	Redpanda EventHub	goal-state.md → Async Event Backbone
13	Roadmap grid (table)	roadmap.md → The grid
14	Year 1 Focus	roadmap.md → Year 1 column
15	Pillar 3: Legacy Retirement	current-state/legacy-integrations.md
16	Open Coordination Items	goal-state.md → Strategic Considerations
17	Non-Goals	goal-state.md → Non-Goals
18	Asks & Next Steps	status.md → Top pending items

Truncation: max 6 bullets per slide, max ~12 words per bullet. Overflow → footer pointer to source.

Theme: document-skills:theme-factory default professional theme. No custom branding on first pass.

Section 4 — Longform PDF spec

Document shape: Cover → TOC → Chapter 1 (current-state.md) → Chapter 2 (goal-state.md) → Chapter 3 (roadmap.md) → Appendix A (current-state/legacy-integrations.md) → Appendix B (current-state/equipment-protocol-survey.md).

Transformations (applied at render time, source markdown not edited):

• File H1 → chapter title
• H2/H3/H4 → numbered sections (1.1, 1.1.1)
• Inter-file links → "see Chapter N" / "see Appendix X"
• _TBD_ markers → visual callout
• ASCII diagrams → preserved as monospace code blocks
• Tables → preserved as multi-page tables

Page setup: Letter, 1" margins, chapter-name running header, page-number + as-of-date footer. document-skills:theme-factory default serif.

Excluded from PDF: status.md, CLAUDE.md, goal-state/digital-twin-management-brief.md, outputs/* (all meta, working, or prep content — not plan content).

Section 5 — Diagrams

Starter set — two diagrams:

1. architecture-layers — the 4-layer stack with IT↔OT boundary. Mermaid flowchart TB.
2. end-to-end-flow — horizontal data flow from equipment to Power BI. Mermaid flowchart LR.

No third roadmap-timeline diagram — the roadmap renders as a PPTX table on slide 13; a Gantt would compete with the grid rather than complement it. Can be added later as diagrams/roadmap-timeline.mmd without changing any other file.

Rendering: on first regeneration, I attempt to render .mmd → .png in-session. If the Claude Code environment has Mermaid rendering available, done. If not, the run log directs the human to render the .mmd file at https://mermaid.live and drop the PNG into outputs/diagrams/. After that, regeneration embeds the existing PNG verbatim — zero drift.

Editing: edit .mmd → re-render PNG → regenerate presentation picks up the new PNG automatically.

Open questions for first-run verification

These get resolved during implementation, not during design:

1. Mermaid rendering in the Claude Code environment. Unknown until I try. Fallback is manual rendering at mermaid.live; neither path breaks the design.
2. Whether document-skills:pptx can produce a 3-column layout (needed for slide 5: Three Pillars) and a 2-column layout (needed for slide 16: Open Coordination Items). If not, the spec falls back to single-column with visual separation.
3. Table overflow behavior on slide 13. The 7×3 roadmap grid with truncated cell content should fit one slide, but if it overflows, the spec needs a fallback: either shrink text or split across two slides.
4. First-pass theme quality. I'll use the theme-factory default; the first output becomes the visual baseline. If it looks wrong, section 3's "visual style" line is where the override goes.

Task list

Implementation tasks are tracked in the native task list:

• #4 — Scaffold outputs/ directory
• #5 — Write outputs/README.md (trigger phrases + checklist)
• #6 — Write outputs/presentation-spec.md
• #7 — Write outputs/longform-spec.md

Additional tasks to be created on entry to implementation:

• Draft architecture-layers.mmd + end-to-end-flow.mmd Mermaid source
• Attempt first PNG rendering (or document manual fallback in run log)
• Execute first PPTX and PDF generation, save to outputs/generated/
• Append inaugural run log entry

What happens after first generation

The first outputs are the baseline. Review produces one of:

• Looks right — done. regenerate outputs works; use it whenever the plan changes.
• Structure wrong — edit presentation-spec.md or longform-spec.md, regenerate.
• Style wrong — note override in spec (theme change, truncation rule tweak), regenerate.
• Content faithful but phrasing drifts between runs — tighten spec rules (e.g., "quote verbatim" instead of "summarize to 5 bullets"), regenerate.

If drift proves unmanageable after a few iterations, the fallback per earlier conversation is to extract the first good output as a template and regenerate against that template instead — turning the pipeline into a content-substitution step against a known-good visual shell. Design section 5's "once the PNG exists" principle (fixed visual, variable text) becomes the model for the whole deck and PDF at that point.