3yearplan/outputs/IMPLEMENTATION-PLAN.md

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

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