# 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