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`](../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.