Initial commit: 3-year shopfloor IT/OT transformation plan
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
164
outputs/DESIGN.md
Normal file
164
outputs/DESIGN.md
Normal 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.
|
||||
Reference in New Issue
Block a user