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
173
outputs/longform-spec.md
Normal file
173
outputs/longform-spec.md
Normal 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.
|
||||
Reference in New Issue
Block a user