dohertj2/3yearplan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: 3-year shopfloor IT/OT transformation plan

Browse Source 
Core plan: current-state, goal-state (layered architecture, OtOpcUa,
Redpanda EventHub, SnowBridge, canonical model, UNS posture + naming
hierarchy, digital twin use cases absorbed), roadmap (7 workstreams x 3
years), and status bookmark.

Component detail files: legacy integrations inventory (3 integrations,
pillar 3 denominator closed), equipment protocol survey template (dual
mandate with UNS hierarchy snapshot), digital twin management brief
(conversation complete, outcome recorded).

Output generation pipeline: specs for 18-slide mixed-stakeholder PPTX
and faithful-typeset PDF, with README, design doc, and implementation
plan. No generated outputs yet — deferred until source data is stable.
This commit is contained in:
Joseph Doherty
2026-04-17 09:12:35 -04:00
commit ec1dfe59e4
15 changed files with 2743 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

164
outputs/DESIGN.md Normal file
View File

@@ -0,0 +1,164 @@
# 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.

275
outputs/IMPLEMENTATION-PLAN.md Normal file
View File

@@ -0,0 +1,275 @@
# Output Generation Pipeline Implementation Plan
> **For Claude:** REQUIRED SUB-SKILL: Use `superpowers-extended-cc:executing-plans` to implement this plan task-by-task. Note: this repo is not a git project and the work is markdown authoring + skill invocation, not code. The standard writing-plans template (TDD, pytest, git commits) does not apply; use the **verification steps** per task as the equivalent of "run the tests."
**Goal:** Scaffold a repeatable PPTX + PDF generation pipeline over the plan markdown source, and produce the first pair of outputs.
**Architecture:** Spec files (`presentation-spec.md`, `longform-spec.md`) as structure anchors; hand-drawn Mermaid diagrams committed as `.mmd` + `.png`; `document-skills:pptx` and `document-skills:pdf` invoked per a fixed checklist in `outputs/README.md`; append-only `run-log.md` records every regeneration.
**Tech Stack:** Markdown, Mermaid (for diagrams), `document-skills:pptx`, `document-skills:pdf`, `document-skills:theme-factory` default theme.
**Design reference:** [`outputs/DESIGN.md`](DESIGN.md)
**Path note:** Writing-plans' default location is `docs/plans/YYYY-MM-DD-<name>.md`; this repo convention keeps documents in topical directories, so this plan lives alongside the pipeline it implements.
---
## Task 0: Directory scaffold
**Status:** Parent directory `outputs/` already exists (created when `DESIGN.md` was written). This task creates the remaining subdirectories.
**Files:**
- Create: `outputs/diagrams/` (directory)
- Create: `outputs/generated/` (directory)
**Step 1:** `mkdir -p outputs/diagrams outputs/generated`
**Step 2: Verify**
Run: `ls outputs/`
Expected: `DESIGN.md IMPLEMENTATION-PLAN.md diagrams generated` (README, specs, run-log not yet created)
---
## Task 1: outputs/README.md — trigger phrases + regeneration checklist
**Files:**
- Create: `outputs/README.md`
**Content requirements:**
- Purpose statement (what `outputs/` is and isn't)
- Trigger phrases section — `regenerate outputs`, `regenerate presentation`, `regenerate longform`
- Numbered regeneration procedure (the 5-step checklist from design section 2)
- Edit-this-not-that rules — when to edit specs vs. source vs. diagrams
- Pointers to `DESIGN.md`, `presentation-spec.md`, `longform-spec.md`, `run-log.md`
**Verification:**
- File exists at `outputs/README.md`
- Contains the three trigger phrases verbatim
- Contains the 5-step procedure numbered 1–5
- Links to the four companion files resolve to existing or soon-to-exist paths
---
## Task 2: outputs/presentation-spec.md — 18-slide PPTX structure anchor
**Files:**
- Create: `outputs/presentation-spec.md`
**Content requirements:**
- Meta header — audience (mixed-stakeholder), theme (theme-factory default), truncation rules (6 bullets, ~12 words each, overflow → footer pointer)
- 18 slide entries, one per slide. Each entry specifies:
- Slide number, title, layout type
- Source file + section anchor
- Population instructions (verbatim / N-bullet summary / diagram embed / table render)
- Optional: notes on layout fallbacks if the PPTX skill can't do the requested layout
- A closing "editing this spec" section explaining that structural changes go here, not in prompts
**Verification:**
- File exists
- Has exactly 18 slide entries
- Every slide cites a specific source file (or `—` for the title slide)
- Slides 8 and 9 reference `outputs/diagrams/architecture-layers.png` and `outputs/diagrams/end-to-end-flow.png` respectively
---
## Task 3: outputs/longform-spec.md — PDF chapter/appendix structure anchor
**Files:**
- Create: `outputs/longform-spec.md`
**Content requirements:**
- Meta header — audience (anyone reading the plan standalone), theme (theme-factory default serif), page setup (Letter, 1" margins, chapter header, page+date footer)
- File-to-chapter mapping:
- Cover page (title, subtitle, as-of date, abstract from `goal-state.md` → Vision)
- TOC (auto, two levels)
- 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`
- Transformation rules (numbered heading, link normalization, `_TBD_` highlight, ASCII diagram preservation, table handling)
- Exclusion list (`status.md`, `CLAUDE.md`, `goal-state/digital-twin-management-brief.md`, `outputs/*`)
**Verification:**
- File exists
- Lists 3 chapters + 2 appendices in the specified order
- Transformation rules section is present and enumerated
---
## Task 4: outputs/diagrams/architecture-layers.mmd — Mermaid source for the 4-layer stack
**Files:**
- Create: `outputs/diagrams/architecture-layers.mmd`
**Content requirements:**
- Mermaid `flowchart TB` (top-to-bottom)
- Nodes: Equipment (bottom) → OtOpcUa (L2, with two namespace sub-nodes) → System Platform + Ignition (L3) → ScadaBridge (L4) → Enterprise IT (Camstar, Delmia, Snowflake, Power BI)
- A visible IT↔OT boundary line between L4 and Enterprise IT (Mermaid supports this via subgraphs or styled edges)
- Labels use the exact vocabulary from `goal-state.md` → Layered Architecture
**Verification:**
- File exists
- Starts with `flowchart TB` or equivalent directive
- Contains node labels for `Equipment`, `OtOpcUa`, `System Platform`, `Ignition`, `ScadaBridge`, and `Enterprise IT`
- Passes basic Mermaid syntax sanity check (paste into mermaid.live renders without error — verify this step on first authoring)
---
## Task 5: outputs/diagrams/end-to-end-flow.mmd — Mermaid source for the data flow
**Files:**
- Create: `outputs/diagrams/end-to-end-flow.mmd`
**Content requirements:**
- Mermaid `flowchart LR` (left-to-right)
- Nodes match `goal-state.md` line 77 exactly: Equipment → OtOpcUa → System Platform/Ignition → ScadaBridge → Redpanda → SnowBridge → Snowflake → dbt → Power BI
- IT↔OT boundary marker between ScadaBridge and Redpanda (Redpanda is IT-adjacent from ScadaBridge's central crossing)
**Verification:**
- File exists
- Starts with `flowchart LR` or equivalent
- Has exactly the 9 nodes in the exact order from `goal-state.md` line 77
- Renders at mermaid.live without error
---
## Task 6: Render diagrams to PNG (or document manual fallback)
**Files:**
- Create: `outputs/diagrams/architecture-layers.png` (if rendering available)
- Create: `outputs/diagrams/end-to-end-flow.png` (if rendering available)
**Step 1:** Attempt to render Mermaid → PNG in the Claude Code environment. Options, in order of preference:
1. `document-skills:pptx` skill may expose a diagram embed path that handles Mermaid natively
2. Python with `mermaid-py` or `mermaid-cli` if available
3. A headless browser with mermaid.js
**Step 2 (if rendering succeeds):** Write the PNGs to `outputs/diagrams/`. Verify file size > 0 and file type is PNG.
**Step 3 (if rendering fails):** Do not block. Instead:
- Create placeholder empty PNGs or skip PNG creation entirely
- Record in the run log: *"Render `outputs/diagrams/architecture-layers.mmd` and `outputs/diagrams/end-to-end-flow.mmd` at https://mermaid.live and save the PNGs to `outputs/diagrams/`. Then re-run `regenerate presentation`."*
- Note in the human-facing summary that this is the one-time manual step
**Verification:**
- Either both PNG files exist with non-zero size, OR the run log contains the explicit manual-render instruction
---
## Task 7: Update CLAUDE.md index
**Files:**
- Modify: `CLAUDE.md`
**Change:** Add `outputs/` to the component detail files list with a one-line description, so future Claude sessions see the pipeline exists when loading the project.
**Verification:**
- `CLAUDE.md` mentions `outputs/` and points to `outputs/README.md` as the regeneration entry point
---
## Task 8: Execute first PPTX generation
**Files:**
- Create: `outputs/generated/plan-presentation.pptx`
**Step 1:** Read `outputs/presentation-spec.md` (the structure anchor).
**Step 2:** Read every source file named in the spec.
**Step 3:** For each of the 18 slides, populate content per the spec's rules.
**Step 4:** Invoke `document-skills:pptx` with:
- Theme: `document-skills:theme-factory` default professional
- Title: "Shopfloor IT/OT Transformation — 3-Year Plan"
- Output path: `outputs/generated/plan-presentation.pptx`
- Diagram images from `outputs/diagrams/`
**Step 5:** Append run log entry.
**Verification:**
- `outputs/generated/plan-presentation.pptx` exists, file size > 0
- Slide count is 18 (verify by re-reading the file's structure if possible)
- Run log has a new entry with timestamp and a "presentation regenerated" note
- If any source content was truncated, a warning appears in the run log entry
---
## Task 9: Execute first PDF generation
**Files:**
- Create: `outputs/generated/plan-longform.pdf`
**Step 1:** Read `outputs/longform-spec.md`.
**Step 2:** Read all 5 source files (current-state.md, goal-state.md, roadmap.md, legacy-integrations.md, equipment-protocol-survey.md).
**Step 3:** Apply the transformation rules from the spec — numbered headings, link normalization, `_TBD_` highlighting.
**Step 4:** Invoke `document-skills:pdf` with:
- Theme: theme-factory default
- Cover page with title, subtitle, as-of date, abstract
- TOC, 3 chapters, 2 appendices
- Output path: `outputs/generated/plan-longform.pdf`
**Step 5:** Append run log entry.
**Verification:**
- `outputs/generated/plan-longform.pdf` exists, file size > 0
- Basic sanity: first page is cover, second is TOC, chapters appear in the expected order
- Run log has a new entry for the PDF generation
- Broken/unresolvable inter-file links are logged as warnings, not silently dropped
---
## Task 10: Initial run log + human-facing summary
**Files:**
- Create: `outputs/run-log.md`
**Content:**
- Header explaining the run log's purpose (append-only audit trail, one entry per regeneration, newest at bottom)
- Inaugural entry:
- Timestamp (2026-04-15)
- What ran: first PPTX + PDF generation
- Source plan version: brief summary ("plan as of 2026-04-15 — 5 source files, 3 legacy integrations, 6 protocol survey placeholder rows")
- Warnings: any truncations, missing sections, broken links, or PNG rendering fallbacks from tasks 6, 8, 9
- Next actions for the human reviewer
**Verification:**
- File exists
- Contains the inaugural entry
- If Task 6 hit the manual-render fallback, the run log surfaces that prominently
---
## Dependencies
```
Task 0 (scaffold)
├── Task 1 (README)
├── Task 2 (presentation-spec)
├── Task 3 (longform-spec)
├── Task 4 (architecture-layers.mmd)
├── Task 5 (end-to-end-flow.mmd)
└── Task 7 (CLAUDE.md index) — can run in parallel
Tasks 4, 5 → Task 6 (render PNGs)
Tasks 1, 2, 6 → Task 8 (PPTX generation)
Tasks 1, 3 → Task 9 (PDF generation)
Tasks 8, 9 → Task 10 (run log)
```
Tasks 0–5 and 7 can run in parallel where sensible; tasks 6, 8, 9, 10 are sequentially dependent.
---
## Out of scope for this plan
- A second theme / branded version of the deck (first run uses theme-factory default; branding iteration is a follow-up)
- A third diagram (roadmap-timeline) — starter set is 2, per design
- A `.claude/commands/regenerate-outputs.md` slash command — plain English trigger + README checklist is enough for first pass
- A curated long-form narrative PDF (option b from earlier brainstorm) — first run is option (a) faithful typeset only
- Editing source plan files — regeneration is read-only on plan content
- Any git operations — this repo is not a git project

110
outputs/README.md Normal file
View File

@@ -0,0 +1,110 @@
# 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`](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, 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`](../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)

173
outputs/longform-spec.md Normal file
View File

@@ -0,0 +1,173 @@
# Longform Spec — Faithful Typeset PDF
**The structure anchor for [`generated/plan-longform.pdf`](generated/).** Every regeneration reads this file first and produces a PDF that renders the current plan markdown as a typeset document with cover, TOC, chapters, and appendices. Edit this file to change PDF structure; do not edit prompts, do not edit the source plan files.
## Meta
| Property | Value |
|---|---|
| **Type** | Faithful typeset (option (a) from the design brainstorm). Structure and headings map 1:1 from source. No curated narrative reshaping. |
| **Audience** | Anyone reading the plan standalone — new stakeholders, archival readers, anyone handed the plan without having followed the day-to-day authoring. |
| **Expected length** | Roughly 50–80 pages depending on rendering density. |
| **Theme** | `document-skills:theme-factory` default professional theme (serif body font). Override by adding a `**Theme override:**` line here. |
| **Page size** | US Letter (8.5" × 11"). Change to A4 if distribution is primarily non-US. |
| **Margins** | 1" on all sides |
| **Running header** | Chapter title (left-aligned) · "Shopfloor IT/OT Transformation — 3-Year Plan" (right-aligned) |
| **Running footer** | Page number (center) · As-of date (right) |
| **Title on cover** | "Shopfloor IT/OT Transformation" |
| **Subtitle on cover** | "3-Year Plan" |
| **Cover as-of line** | "As of {{regeneration-date}}" |
| **Cover abstract** | A single paragraph lifted **verbatim** from [`../goal-state.md`](../goal-state.md) → **Vision** (the opening paragraph). Do not paraphrase. |
## Document structure
```
Cover page — title, subtitle, as-of date, abstract
Table of Contents — auto-generated, two levels deep
Chapter 1 — Current State (source: ../current-state.md)
Chapter 2 — Goal State (source: ../goal-state.md)
Chapter 3 — Roadmap (source: ../roadmap.md)
Appendix A — Legacy Integrations Inventory (source: ../current-state/legacy-integrations.md)
Appendix B — Equipment Protocol Survey (source: ../current-state/equipment-protocol-survey.md)
```
**Chapter / appendix file-to-source mapping:**
| Label | Title | Source file |
|---|---|---|
| Chapter 1 | Current State | [`../current-state.md`](../current-state.md) |
| Chapter 2 | Goal State | [`../goal-state.md`](../goal-state.md) |
| Chapter 3 | Roadmap | [`../roadmap.md`](../roadmap.md) |
| Appendix A | Legacy Integrations Inventory | [`../current-state/legacy-integrations.md`](../current-state/legacy-integrations.md) |
| Appendix B | Equipment Protocol Survey | [`../current-state/equipment-protocol-survey.md`](../current-state/equipment-protocol-survey.md) |
## Explicitly excluded
These files are **not** part of the PDF — do not include them even if they seem relevant:
| File | Why excluded |
|---|---|
| [`../CLAUDE.md`](../CLAUDE.md) | Repo meta — instructions for Claude, not plan content. |
| [`../status.md`](../status.md) | Working bookmark — a session-state artifact, not authoritative plan content. |
| [`../goal-state/digital-twin-management-brief.md`](../goal-state/digital-twin-management-brief.md) | Meeting prep artifact. Its own header explicitly says it is not plan content. |
| [`./README.md`](README.md), [`./DESIGN.md`](DESIGN.md), [`./presentation-spec.md`](presentation-spec.md), [`./longform-spec.md`](longform-spec.md), [`./IMPLEMENTATION-PLAN.md`](IMPLEMENTATION-PLAN.md), [`./run-log.md`](run-log.md) | Output pipeline files — the pipeline does not document itself inside its own output. |
| [`./diagrams/*`](diagrams/), [`./generated/*`](generated/) | Output pipeline artifacts. |
If a new plan file is added to the repo and should be in the PDF, **add it here**, under Document structure, as a new chapter or appendix — not in the source file and not in the prompt.
## Transformations applied during rendering
The narrow set of changes applied to source markdown when producing the PDF. Source markdown files are **not edited** — transformations are applied at render time.
### 1. File H1 → chapter/appendix title
`# Current State` (the first line of `current-state.md`) becomes the chapter title *"Chapter 1 — Current State"* on the chapter's opening page. The H1 is consumed by the chapter heading; it does not appear a second time in the body.
### 2. Heading numbering
All `##`, `###`, `####` headings receive section numbers:
- `##` → `N.M` where N = chapter number, M increments per ## within the chapter
- `###` → `N.M.K`
- `####` → `N.M.K.L`
Example: `## Systems & Interfaces` in Chapter 1 becomes `1.2 Systems & Interfaces`.
Numbering is **added at render time**; source markdown remains unchanged. Numbering is **applied to body text** but **not to the TOC** (TOC uses unnumbered section titles for readability).
### 3. Inter-file link normalization
Markdown links between plan files are resolved to section references in the rendered PDF:
| Source link form | Rendered form |
|---|---|
| `[current-state.md](current-state.md)` | "see Chapter 1 — Current State" |
| `[goal-state.md](goal-state.md)` | "see Chapter 2 — Goal State" |
| `[roadmap.md](roadmap.md)` | "see Chapter 3 — Roadmap" |
| `[legacy-integrations.md](current-state/legacy-integrations.md)` | "see Appendix A — Legacy Integrations Inventory" |
| `[equipment-protocol-survey.md](current-state/equipment-protocol-survey.md)` | "see Appendix B — Equipment Protocol Survey" |
| Intra-file anchor links like `[X](#section-name)` | Rendered as internal PDF cross-reference to the numbered section (e.g., "see §1.2") |
| Links to excluded files (e.g., `status.md`, `digital-twin-management-brief.md`) | Rendered as **plain text** — the link target is dropped, the link text stays. Logged as a warning in the run log. |
| External links (http://, https://) | Rendered as clickable external links, unchanged. |
| Unresolvable links (file not found) | Rendered as plain text, logged as a warning in the run log. **Do not silently drop.** |
### 4. `_TBD_` marker highlighting
Every occurrence of `_TBD_` in the source becomes a **visual callout** in the rendered PDF:
- Inline `_TBD_` tokens get a colored background (theme-appropriate warning color)
- A small margin icon (⚑ or similar) in the left margin on lines containing a TBD
- TBDs remain readable — the goal is visibility, not obstruction
This makes the "gaps stay visible" convention from [`../CLAUDE.md`](../CLAUDE.md) → Conventions actually visible on paper.
### 5. ASCII / text diagrams preserved
The Layered Architecture text diagram in `goal-state.md` (and any similar text diagrams elsewhere) renders as a monospace code block with a subtle border. Option (a) faithful typeset explicitly accepts this — proper visual diagrams live in the PPTX, not the PDF.
### 6. Tables preserved (with multi-page support)
Markdown tables render as PDF tables with row-level borders and header-row emphasis. Tables that exceed one page split cleanly at row boundaries, with the header row repeated at the top of each continuation page. `document-skills:pdf` handles this natively.
Specific large tables to expect:
- [`../roadmap.md`](../roadmap.md) → **The grid** (7 workstreams × 3 years) — likely spans 2–3 pages
- [`../current-state/legacy-integrations.md`](../current-state/legacy-integrations.md) → per-row integration detail tables (one per integration)
- [`../current-state/equipment-protocol-survey.md`](../current-state/equipment-protocol-survey.md) → field schema table, classification table, rollup views
### 7. Code blocks preserved
Fenced code blocks in the source (for example, the directory-structure `dot` block in [`../goal-state.md`](../goal-state.md) or the structure trees in this file) render as monospace blocks with a light background. Line wrapping preferred over horizontal scroll.
### 8. Block quotes preserved
Markdown `>` block quotes render as indented italic or colored blocks per the theme. Several key notes in the source (file headers, carve-outs) use block quotes and their emphasis is load-bearing.
### 9. Emphasis preserved
`**bold**`, `*italic*`, and `` `inline code` `` all render as expected. The source uses these deliberately (especially bold for decisions and vocabulary terms) — preserve fidelity.
## Front matter
### Cover page
```
[Large type] Shopfloor IT/OT Transformation
[Medium type] 3-Year Plan
[Small type] As of {{regeneration-date}}
[Body paragraph, centered or full-width]
{{abstract — verbatim from ../goal-state.md → Vision, opening paragraph}}
```
### Table of Contents
- Auto-generated from chapter and appendix headings
- **Two levels deep:** chapter titles + `##` headings within each chapter
- Unnumbered in the TOC for readability (numbering appears in body)
- Page numbers right-aligned
- Leaders (`.....`) between heading text and page number
- Chapters and appendices visually distinguished (slight indent, different weight, or section label)
### Back matter
- **No index.** Generating a useful index requires curation; automated indexing produces noise. Skip for the first pass.
- **No glossary.** Plan vocabulary (OtOpcUa, ScadaBridge, SnowBridge, Redpanda, etc.) is defined at first use in the source. If readers need a glossary, that's a future enhancement.
## Editing this spec
- **Structural changes go here** — chapter order, appendix additions, cover layout, page setup, transformation rules.
- **Content changes go in the source** — typos, new sections, corrections to the plan. The next regeneration picks them up automatically.
- **Theme / page-setup changes go in the Meta section** at the top of this file. Override with a `**Theme override:**` or `**Page size override:**` line.
- **Never hand-edit `generated/plan-longform.pdf`.** It is overwritten on the next regeneration.
## Planned follow-ups (not first-pass scope)
These are deliberately deferred:
- **Curated executive-narrative PDF** (option (b) from the design brainstorm) — a second output shaped as a standalone written report with intro, argument flow, transitions. Would live at `generated/plan-narrative.pdf` with its own `narrative-spec.md`.
- **Bilingual rendering** — if the plan ever serves a non-English audience.
- **Redacted variant** — a version with sensitive detail removed, for external stakeholders.
- **Date-stamped archival copies** — `generated/plan-longform-YYYY-MM-DD.pdf` alongside the current one, so the history of the plan is preserved as a series of snapshots.
None of these require changes to the current spec; add them when/if they become real requirements.

206
outputs/presentation-spec.md Normal file
View File

@@ -0,0 +1,206 @@
# Presentation Spec — Mixed-Stakeholder Deck
**The structure anchor for [`generated/plan-presentation.pptx`](generated/).** Every regeneration reads this file first and populates slides exactly as described below. Edit this file to change deck structure; do not edit prompts, do not edit the source plan files.
## Meta
| Property | Value |
|---|---|
| **Audience** | Mixed stakeholder — steering committee, leadership, build team leads, adjacent-initiative owners. Some execs, some technical. |
| **Total slides** | 18 |
| **Target read time** | 30–45 minutes walked through, ~10 minutes self-read |
| **Theme** | `document-skills:theme-factory` default professional theme. Clean, neutral, no custom branding on first pass. Override: add a `**Theme override:**` line here with the target preset if you want different. |
| **Body font** | Theme default sans-serif |
| **Accent color** | Theme default |
| **Source of truth for title** | "Shopfloor IT/OT Transformation — 3-Year Plan" |
| **Subtitle template** | "As of {{date}}" where `{{date}}` is the regeneration timestamp in `YYYY-MM-DD` form |
## Truncation rules (apply to every slide unless overridden per-slide)
- **Max 6 bullets per slide.** If the source section has more than 6 bullets of load-bearing content, pick the 6 most load-bearing and add a footer line: *"Full detail: `<source file> → <section name>`."*
- **Max ~12 words per bullet.** Aim for scan-ability, not completeness.
- **No nested bullets.** If the source has nested bullets, flatten to one level by merging or dropping sub-points.
- **Preserve source vocabulary.** Use the same words the plan uses (e.g., "OtOpcUa," "ScadaBridge," "SnowBridge," "pillar 3," "data locality," "single sanctioned crossing point") — don't paraphrase technical terms or the Vision line.
- **TBDs stay visible.** If a source section contains a `_TBD_` that is load-bearing for the slide's point, call it out explicitly: *"(TBD — see source.)"* Don't silently drop TBDs.
- **Overflow callout.** When content is truncated, the footer line *"Full detail: `<source file> → <section name>`"* appears in small text at the bottom of the slide.
## Layout fallbacks
If `document-skills:pptx` cannot render a requested layout:
- **3-column content → single column with visual separators.** Applies to slide 5 (Three Pillars).
- **2-column content → single column with a horizontal rule.** Applies to slide 16 (Open Coordination Items).
- **Diagram + caption → caption only with a "(Diagram not yet available — render `<path>.mmd` and re-run)" note.** Applies to slides 8 and 9 until the PNG files exist in `diagrams/`.
- **Multi-column table that overflows → split across two slides labeled "N/2" and "2/2".** Applies to slide 13 (Roadmap grid) if 7 rows × 3 columns doesn't fit one slide at readable type size.
---
## Slide 1 — Title
| Property | Value |
|---|---|
| **Layout** | Title |
| **Source** | — (no source file) |
| **Content** | Title: *"Shopfloor IT/OT Transformation"* · Subtitle: *"3-Year Plan"* · Footer: *"As of {{regeneration-date}}"* |
| **Rules** | No bullets, no extra content. Title slide is deliberately minimal. |
## Slide 2 — Executive Summary
| Property | Value |
|---|---|
| **Layout** | Content (bulleted) |
| **Source** | [`../goal-state.md`](../goal-state.md) → **Vision** + **Success Criteria** |
| **Population** | 5 bullets: (1) the Vision line verbatim, (2)–(4) one line per pillar (the binary success criterion, not the rationale), (5) a single line naming the key non-goals in the form *"Out of scope: operator UX modernization, licensing, VM-level DR, physical network segmentation."* |
| **Notes** | This slide is the TL;DR for anyone who reads only one slide. Keep it tight. |
## Slide 3 — Today's Reality
| Property | Value |
|---|---|
| **Layout** | Content (bulleted) |
| **Source** | [`../current-state.md`](../current-state.md) — synthesize from Systems & Interfaces and Equipment OPC UA sections |
| **Population** | 5 bullets describing the pain points of the current state: (1) split SCADA stack (Aveva + Ignition by purpose), (2) WAN-dependent central Ignition with direct OPC UA sessions to site equipment, (3) multiple concurrent OPC UA sessions to the same equipment, (4) legacy IT↔OT integrations outside ScadaBridge (3 of them), (5) fragmented data access and inconsistent values between consumers |
| **Notes** | The source file doesn't have a dedicated "pain points" section (it's a `_TBD_`). Synthesize from the inline observations in Systems & Interfaces and Equipment OPC UA. Don't invent pain points that aren't grounded in the source. |
## Slide 4 — Vision
| Property | Value |
|---|---|
| **Layout** | Big-text / quote layout |
| **Source** | [`../goal-state.md`](../goal-state.md) → **Vision** |
| **Population** | The Vision line ("stable, single point of integration between shopfloor OT and enterprise IT") as the centerpiece. 3 sub-bullets below it on what that means concretely — extracted from the paragraph that follows the Vision line in goal-state.md. |
| **Notes** | This slide repeats the Vision from slide 2 deliberately — slide 2 is the 30-second summary; slide 4 is where the Vision actually gets the airtime the conversation will return to. |
## Slide 5 — Three Pillars
| Property | Value |
|---|---|
| **Layout** | 3-column content (fallback: single column with visual separators) |
| **Source** | [`../goal-state.md`](../goal-state.md) → **Success Criteria** |
| **Population** | Column 1: Pillar 1 — Unification (100% of sites on standardized stack). Column 2: Pillar 2 — Analytics/AI Enablement (≤15-minute analytics SLO; one "not possible before" use case in production). Column 3: Pillar 3 — Legacy Retirement (inventory to zero). Each column: (a) title, (b) the binary criterion in one line, (c) one line of "what this means" context. |
| **Rules** | All three pillars must appear. Do not prioritize one over the others here — they are equal end-state criteria per the plan. |
## Slide 6 — Enterprise Layout
| Property | Value |
|---|---|
| **Layout** | Content (bulleted, grouped by tier) |
| **Source** | [`../current-state.md`](../current-state.md) → **Enterprise Layout** |
| **Population** | Grouped bullets: (a) Primary Data Center — South Bend. (b) Largest Sites — Warsaw West, Warsaw North (one cluster per building). (c) Other Integrated Sites — Shannon, Galway, TMT, Ponce (single cluster per site). (d) Not Yet Integrated — Berlin, Winterthur, Jacksonville (and others, with volatility note). |
| **Notes** | The volatility note about smaller sites changing belongs on the slide as a one-line disclaimer at the bottom. |
## Slide 7 — Today's Systems
| Property | Value |
|---|---|
| **Layout** | Content (bulleted) |
| **Source** | [`../current-state.md`](../current-state.md) → **Systems & Interfaces** |
| **Population** | 6 bullets, one line each: (1) Aveva System Platform — validated data collection; (2) Ignition SCADA — KPI monitoring (central, WAN-dependent); (3) ScadaBridge — in-house Akka.NET integration layer, already deployed; (4) LmxOpcUa — in-house OPC UA server exposing System Platform objects; (5) Camstar MES — sole enterprise MES; (6) Aveva Historian — sole historian, central-only, permanent retention. |
| **Notes** | Delmia DNC is mentioned as one of the two legacy Web API interfaces but does not need its own bullet here — it's captured on slide 15. |
## Slide 8 — Goal State: Layered Architecture
| Property | Value |
|---|---|
| **Layout** | Diagram + caption |
| **Source** | [`../goal-state.md`](../goal-state.md) → **Layered Architecture** + [`diagrams/architecture-layers.png`](diagrams/) |
| **Population** | Embed `diagrams/architecture-layers.png` as the centerpiece. Caption: one line per layer — *"Layer 1 Equipment · Layer 2 OtOpcUa (equipment + System Platform namespaces) · Layer 3 SCADA (System Platform + Ignition) · Layer 4 ScadaBridge (IT↔OT bridge)"*. Callout: *"ScadaBridge central is the sole IT↔OT crossing point."* |
| **Fallback** | If `architecture-layers.png` does not exist, render a placeholder box with the text *"Diagram not yet available — render `diagrams/architecture-layers.mmd` at https://mermaid.live and save PNG to `diagrams/architecture-layers.png`, then re-run `regenerate presentation`."* |
## Slide 9 — Goal State: End-to-End Data Flow
| Property | Value |
|---|---|
| **Layout** | Diagram + caption |
| **Source** | [`../goal-state.md`](../goal-state.md) → the tag-flow sentence (search for "A tag read from a machine in Warsaw West") + [`diagrams/end-to-end-flow.png`](diagrams/) |
| **Population** | Embed `diagrams/end-to-end-flow.png`. Caption: the tag-flow sentence from goal-state.md, verbatim or near-verbatim. |
| **Fallback** | Same fallback pattern as slide 8, but for `end-to-end-flow.mmd` / `.png`. |
## Slide 10 — OtOpcUa — the unification layer
| Property | Value |
|---|---|
| **Layout** | Content (bulleted) |
| **Source** | [`../goal-state.md`](../goal-state.md) → **OtOpcUa — the unified site-level OPC UA layer** |
| **Population** | 6 bullets: (1) single sanctioned OPC UA access point per site, one session per equipment; (2) two namespaces — equipment + System Platform (absorbs LmxOpcUa); (3) clustered, co-located on existing System Platform nodes; (4) hybrid driver strategy — proactive core library + on-demand long-tail; (5) OPC UA-native auth (UserName + standard security modes, inherited from LmxOpcUa); (6) tiered cutover — ScadaBridge → Ignition → System Platform IO across Years 1–3. |
## Slide 11 — Analytics Stack: SnowBridge, Snowflake, dbt
| Property | Value |
|---|---|
| **Layout** | Content (bulleted) |
| **Source** | [`../goal-state.md`](../goal-state.md) → **SnowBridge** + **Aveva Historian → Snowflake** + **Snowflake-side transform tooling** |
| **Population** | 6 bullets: (1) SnowBridge — custom-built machine-data-to-Snowflake upload service; (2) source abstraction — Aveva Historian SQL in Year 1, Redpanda/ScadaBridge in Year 2; (3) governed selection with blast-radius approval workflow; (4) dbt curated layers, orchestrator out of scope; (5) ≤15-minute analytics SLO; (6) one "not possible before" AI/analytics use case in production by end of plan (pillar 2 gate). |
## Slide 12 — Redpanda EventHub: the async backbone
| Property | Value |
|---|---|
| **Layout** | Content (bulleted) |
| **Source** | [`../goal-state.md`](../goal-state.md) → **Async Event Backbone** |
| **Population** | 6 bullets: (1) self-hosted, central in South Bend (single-cluster HA); (2) per-topic tiered retention — operational 7d / analytics 30d / compliance 90d; (3) bundled Schema Registry; (4) Protobuf schemas in central `schemas` repo with `buf` CI, `BACKWARD_TRANSITIVE` compatibility; (5) `{domain}.{entity}.{event-type}` topic naming, site identity in message not topic; (6) SASL/OAUTHBEARER auth + prefix ACLs. |
## Slide 13 — 3-Year Roadmap (workstreams × years)
| Property | Value |
|---|---|
| **Layout** | Table — 7 rows × 3 columns (+ workstream name column = 4 columns total) |
| **Source** | [`../roadmap.md`](../roadmap.md) → **The grid** |
| **Population** | Render the 7×3 roadmap grid as a PPTX table. **Truncate** each cell to the **single most important commitment** (not the full cell text, which would overflow). Workstream column: full name. Year columns: ~10-word headline per cell. Color-code cells by pillar if the theme supports it. |
| **Fallback** | If the 7×3 table doesn't fit one slide at readable type size, split across two slides: workstreams 1–4 on slide 13a (OtOpcUa, Redpanda, SnowBridge, dbt), workstreams 5–7 on slide 13b (ScadaBridge Extensions, Site Onboarding, Legacy Retirement). Label slides 13 and 14, renumber subsequent slides. |
## Slide 14 — Year 1 Focus
| Property | Value |
|---|---|
| **Layout** | Content (bulleted) |
| **Source** | [`../roadmap.md`](../roadmap.md) → the Year 1 column across all 7 workstreams |
| **Population** | 7 bullets, one per workstream, ordered by prerequisite position: (1) OtOpcUa — evolve LmxOpcUa, protocol survey, deploy to every site, begin tier-1 cutover; (2) Redpanda — stand up central cluster, schema registry, initial topics; (3) SnowBridge — design + first source adapter (Historian SQL) with filtered flow; (4) dbt — scaffold project, first curated model; (5) ScadaBridge Extensions — deadband publishing + EventHub producer; (6) Site Onboarding — document lightweight onboarding pattern (no new sites Year 1); (7) Legacy Retirement — populate inventory (done), retire first integration as pattern-proving exercise. |
| **Rules** | **Exceeds the 6-bullet truncation rule.** 7 bullets here is intentional because each bullet represents one workstream's Year 1 commitment — dropping one would misrepresent the plan. Keep all 7, tighten wording to ≤10 words per bullet. |
## Slide 15 — Pillar 3: Legacy Retirement (3 → 0)
| Property | Value |
|---|---|
| **Layout** | Content (bulleted + callout) |
| **Source** | [`../current-state/legacy-integrations.md`](../current-state/legacy-integrations.md) → Current inventory |
| **Population** | 3 bullets — one per legacy integration: (1) **LEG-001** Aveva Web API → Delmia DNC (bidirectional orchestrated handshake; harder retirement — requires ScadaBridge scripts to re-implement System Platform parse logic). (2) **LEG-002** Aveva Web API ← Camstar MES (Camstar-initiated; easier retirement — ScadaBridge already has native Camstar path; requires Camstar-side reconfiguration). (3) **LEG-003** System Platform → custom email notification service (easier retirement — ScadaBridge native notifications already exist). Callout at bottom: *"Historian MSSQL reporting surface (BOBJ / Power BI) is explicitly carved out as not legacy — see `legacy-integrations.md` → Deliberately not tracked."* |
## Slide 16 — Open Coordination Items
| Property | Value |
|---|---|
| **Layout** | 2-column content (fallback: single column with horizontal rule) |
| **Source** | [`../goal-state.md`](../goal-state.md) → **Strategic Considerations (Adjacent Asks)** |
| **Population** | **Left column — Digital Twin:** 4 bullets: (1) Management ask, not a committed workstream; (2) Plan shaped to serve if it materializes (OtOpcUa, Redpanda, Snowflake); (3) 8 clarification questions + 4-bucket decision framework ready; (4) Next: schedule management conversation — brief at `goal-state/digital-twin-management-brief.md`. **Right column — BOBJ → Power BI:** 4 bullets: (1) In-flight reporting initiative, not owned by this plan; (2) Three consumption paths analyzed (Snowflake dbt / Historian direct / both); (3) Recommended position: Path C — hybrid, with Path A as strategic direction; (4) Next: schedule coordination conversation with reporting team — 8 questions ready in `goal-state.md`. |
## Slide 17 — Non-Goals
| Property | Value |
|---|---|
| **Layout** | Content (bulleted) |
| **Source** | [`../goal-state.md`](../goal-state.md) → **Non-Goals** |
| **Population** | 6 bullets, one line each: (1) Operator UX modernization — deprioritized against the three pillars; (2) Support staffing decisions — other teams; (3) Licensing strategy — not tracked; (4) Self-hosted orchestrator selection — chosen outside this plan; (5) VM-level DR — out of scope for Redpanda; (6) Physical network segmentation — out of scope. |
| **Notes** | This slide is important for managing stakeholder expectations — what the plan *does not* commit to is as load-bearing as what it does commit to. Do not drop this slide even if time is short. |
## Slide 18 — Asks & Next Steps
| Property | Value |
|---|---|
| **Layout** | Content (bulleted) |
| **Source** | [`../status.md`](../status.md) → **Top pending items** + inferred from [`../roadmap.md`](../roadmap.md) → Year 1 |
| **Population** | 5 bullets: (1) Sponsor confirmation + Year 1 funding commitment; (2) Named owners for each of the 7 workstreams (build team alignment); (3) Digital Twin management conversation — schedule (see brief); (4) Power BI coordination conversation with reporting team — schedule; (5) Equipment protocol survey owner named (Q1 Year 1 prerequisite for OtOpcUa core driver library). |
| **Notes** | This is the closer slide. Each bullet should be a discrete ask with a clear "who needs to do what" so the audience leaves with action. |
---
## Editing this spec
- **Structural changes go here.** If you want to add, remove, reorder, or reshape a slide, edit this file. Don't edit the prompt ("regenerate presentation") and don't edit the source plan files.
- **Content changes go in the source.** If a slide's content is wrong because the plan itself is wrong, edit the source plan file (`current-state.md`, `goal-state.md`, `roadmap.md`, etc.) — the next regeneration will pick up the change automatically because this spec references the source file, not a snapshot.
- **Theme / visual changes go in the meta section at the top of this file.** Add a `**Theme override:**` line naming the target preset, or tweak the truncation rules. First regeneration uses theme-factory default; iterate from there.
- **Never edit `generated/plan-presentation.pptx` by hand.** Any hand-edits are overwritten on the next regeneration. If you find yourself wanting to hand-edit, the correct move is to edit this spec and regenerate.
## Slide-count budget
Current: **18 slides.** If additions push this above 22, reconsider whether the deck is still "mixed-stakeholder" or has quietly become a build-team deck. The mixed-stakeholder audience tops out around 20 slides before attention fragments; a build-team deck belongs in a separate spec file (`build-team-spec.md` or similar) feeding a second generated output.