Gtm Parametric Demo Reports

---
name: gtm-parametric-demo-reports
version: 1.0.0
category: business
description: "Create parametric engineering demo reports (HTML+PDF) for cold outreach to marine/offshore contractors. Data-first architecture: input DBs → parametric sweep → output DBs → comparison matrices → branded interactive report."
type: workflow
capabilities:
- parametric_engineering_analysis
- interactive_html_reports
- vessel_structure_comparison
- cold_outreach_collateral
requires: []
trigger: manual
---

# GTM Parametric Demo Reports

> Workflow for building self-contained interactive HTML engineering reports as cold outreach sales collateral. The report IS the deliverable -- not a mockup.

## When to Use

- Building demo/sample reports to send to prospective clients
- Creating parametric engineering studies that showcase capability
- Comparing vessels, structures, pipe sizes, or codes across a matrix
- Any "overnight engineering" demonstration

## Cold Outreach Design Principles

1. **Self-explanatory** -- no one walks them through it; must stand alone
2. **Case-count headline** -- lead with volume: "108 cases screened overnight"
3. **First 5 seconds matter** -- the headline must trigger: "this would take my team 2 weeks"
4. **Real deliverable feel** -- not a toy, not a slide deck
5. **Defensible engineering** -- proper code clause refs, safety factors, material data; senior engineers will spot-check
6. **LIVE MODE teaser** -- plant seed for higher-value retainer: "In LIVE MODE, feed VMMS/IMMS for real-time go/no-go"

## Data Architecture (Three Layers)

### Layer 1: Input Databases (`gtm/data/`)

Create JSON databases per category BEFORE writing any demo code:

| File | Purpose |
|------|---------|
| `pipelines.json` | Pipe catalog: OD, WT schedules, grades, SMYS/SMTS, submerged weight |
| `csv_hlv_vessels.json` | Construction vessels: crane curves (SWL vs radius), dims, RAOs |
| `pipelay_vessels.json` | Pipelay vessels: tensioner capacity, stinger config, depth range |
| `ctv_operability_<site>.json` | CTV/SOV access-operability reference data: landing arrangements, monthly weather-window/workability, headline uplift metrics. Only place under `gtm/data/` after explicit GTM-use/rights approval; otherwise keep in `references/vessel-suitability/data/` as `internal_reference_only`. |
| `mudmat_structures.json` | Structures: dims, mass, CoG, hydro coefficients (C_s, C_D, C_a) |
| `rigid_jumpers.json` | Jumpers: length, OD, WT, mass per meter, total mass |
| `freespan_scenarios.json` | Environmental: currents, span lengths, soil types, gap ratios |
| `design_codes.json` | Code metadata: safety factors, clause refs, edition years |

**Key rule**: Calculate derived values (mass/m, submerged weight) from first principles using a calc script, don't guess. Include `_description`, `_version`, `_references` in every JSON.

### Layer 2: Output Results (`gtm/results/`)

One JSON per demo, array of case objects. Every case has:
```json
{
  "case_id": "XXX-001",
  "inputs": { "vessel": {...}, "structure": {...}, "environment": {...} },
  "results": { "utilisation": N, "status": "PASS|FAIL", "governing_check": "..." },
  "code_ref": "DNV-RP-XXXX Sec Y.Z",
  "timestamp": "ISO-8601"
}
```

Create schema files with `null` result values BEFORE building the demo scripts. This forces you to think through the output structure.

### Layer 3: Comparison Matrices (`gtm/results/`)

Two cross-demo aggregation files:

**vessel_comparison_matrix.json** -- "What can each vessel do?"
- Per vessel: go/no-go grid across all structures x depths
- Head-to-head: Vessel A vs B, where does one become limited?
- Overall score: total pass rate, strongest/weakest capability

**structure_comparison_matrix.json** -- "Which structure is hardest?"
- Per category: compare structures on same vessel at same depth
- Breakpoints: at what size/weight/length does it go from GO to NO_GO
- Code comparison: which code is most conservative, weight penalty %

## Report Format (HTML + PDF)

- **Primary**: Interactive HTML with embedded Plotly (single .html file, works offline)
- **Fallback**: PDF via print-friendly CSS (`@media print` in same HTML)
- Both from same Python script
- **Same-day client pack**: when existing GTM HTML exists and the user needs PDFs immediately, generate a branded PDF pack directly from those HTML reports with headless Chrome, add a pack index, visible caveats, and a PDF-only ZIP for email. See `references/client-pdf-packaging.md`.
- **Repo ecosystem flowchart collateral**: when a prospect/pilot conversation needs a one-page explanation of how the engineering consulting repo ecosystem works, review live tier-1 repo roles, draft a self-contained HTML flowchart with clickable GitHub repo links, render to a one-page PDF, and verify page count/text/links. See `references/repo-ecosystem-flowchart-collateral.md`.
- **Pipeline-company brochure pack**: for pipeline/subsea prospects, package wall thickness multi-code screening, rigid jumper freespan/VIV screening, and optional rigid jumper installation/vessel suitability into a concise HTML+PDF+email bundle. See `references/pipeline-company-brochure-pack.md`.
- **Field-development consulting outreach**: when drafting email to a field development / subsea engineering consulting company, start from `templates/field-development-consulting-outreach.md`; lead with concrete analysis-pack deliverables, low-risk pilot framing, and a 30-minute review ask.
- **Offshore intervention / HSE / riser outreach**: for prospect-specific outreach around intervention, abandonment, HSE inputs, and riser/OrcaFlex automation, prepare a PII-safe strategy plan and minimum credible collateral packet before sending email. See `references/offshore-intervention-hse-riser-outreach.md`.

### HTML Template Requirements
- digitalmodel branding (header, colors)
- Plotly charts (hover, zoom, pan)
- Color-coded pass/fail tables (green/red/amber)
- Methodology section with code clause references
- Assumptions and limitations footer
- LIVE MODE teaser section at bottom
- Case count in the title: "84 Freespan Cases Screened Overnight"

## Workflow Steps

1. **Discuss scope** -- nail down parameter matrix, audience, pitch
2. **Create input databases** -- JSON files with real engineering values
3. **Create output schemas** -- empty result templates with null values
4. **Create comparison matrix templates** -- vessel x structure grids
5. **Identify data gaps** -- spin GH issues for missing data (e.g. vessel specs)
6. **Build demo scripts** -- start with demos that have all data available
7. **Generate reports** -- run scripts, populate results, build HTML
8. **Populate comparison matrices** -- aggregate across demos

## Pitfalls

- **Result filenames drift from demo names**: don't infer result filenames from script names. For rigid jumper/freespan VIV, the verified output is `results/demo_01_freespan_results.json` (not `demo_01_freespan_viv_results.json`). Open the JSON metadata before declaring a result missing.
- **Pipeline prospect collateral has a proven triad**: wall thickness multi-code screening (Demo 2), rigid jumper freespan/VIV screening (Demo 1), and optional rigid jumper installation/vessel suitability (Demo 5). See `references/pipeline-company-brochure-pack.md`.
- **Smaller installation vessel owner wedge**: for regional CSV/MPSV/ROV-support owners and light-construction contractors, lead with vessel suitability rather than pipeline design: "one vessel data sheet + one representative jumper/mudmat/pipelay scope → client-ready GO/NO_GO envelope." Use practical tender-support language (capability envelope, limiting criterion, governing phase, crane/tensioner/deck-space bottlenecks) and keep PII outside Git. Reference pattern: `aceengineer-strategy/pipeline/proposals/small-installation-vessel-owners-gtm-2026-05-07.md`.
- **Prospect-specific offshore automation outreach**: when a named prospect requires intervention/abandonment, offshore HSE, and riser-analysis positioning, do not jump straight to an email. First verify public role context, keep private contact data out of Git, inspect `worldenergydata` and `digitalmodel` capability anchors, draft a strategy-side plan, create a tracking issue, and define the three one-pagers needed before send. See `references/offshore-intervention-hse-riser-outreach.md`.
- **Outreach logs must be PII-safe**: document sent emails in `aceengineer-strategy/pipeline/conversations.md` using role/company descriptors only; keep names and direct contact details out of Git.
- **Prospect email language**: use low-risk pilot / fixed-fee starter / 30-minute review language with concrete deliverables; avoid desperation or "survival pricing" framing. For field-development engineering consulting companies, emphasize early-phase option screening, subsea pipeline wall thickness, rigid jumper freespan/VIV, and vessel/installation suitability as reusable client-ready packs; use `templates/field-development-consulting-outreach.md` rather than drafting from scratch.
- **Don't let missing data block everything**: Create representative/generic databases, spin GH issues for real data, build demos with what you have. Swap real data in later.
- **Vessel suitability has two layers**: separate raw/reference intake and GTM packaging from deeper engineering implementation. Add a traceability index for the actual reference corpus reviewed, then create/link a GTM issue for scoring/report output rather than overloading the engineering anchor issue. See `references/vessel-suitability-reference-intake.md`.
- **Access operability is not the same as vessel specs**: CTV/SOV workability infographics belong in a separate access-operability dataset with source caveats, not merged into CSV/HLV or pipelay vessel databases. If rights/GTM approval is not explicit, keep the dataset under `references/vessel-suitability/data/` as `internal_reference_only` and remove any generated GTM HTML/PDF/index derivatives. See `references/ctv-access-operability-reference-flow.md`.
- **PDF generation needs artifact verification**: headless Chrome can exit successfully while assets/JS render poorly or files are absent; always check non-zero PDF sizes and, when available, `pdfinfo`/`pdftotext` before reporting. See `references/client-pdf-packaging.md`.
- **Vessel data is always the hardest to get**: Crane curves, RAOs need public spec sheets or industry databases. Pipeline data is easy (API 5L tables).
- **Senior engineers spot-check numbers**: If wall thickness or safety factors look wrong, the entire demo loses credibility. Use real code formulas.
- **Email attachment gotcha**: Some corporate email servers block .html files. Zip it or host on a link. PDF fallback covers this.
- **Case count is the hook**: "36 cases" doesn't impress. Aim for 50-200+ cases per demo to trigger "this would take weeks."

## Shared Report Template (report_template.py)

The GTMReportBuilder class handles all branding, charts, and PDF export. Key API:

```python
from report_template import GTMReportBuilder, COLORS, CHART_PALETTE

report = GTMReportBuilder(
    title="Pipeline Wall Thickness — Multi-Code Comparison",
    subtitle="72 parametric cases across 6 pipe sizes and 3 design codes",
    demo_id="demo_02",
    case_count=72,
    code_refs=["DNV-ST-F101 (2021)", "API RP 1111 (2015)", "PD 8010-2 (2015)"],
)
report.add_methodology("<p>...</p>")          # Goes first
report.add_chart("chart_id", plotly_fig, title="...", subtitle="...")
report.add_table("title", df, status_col="Status")  # Auto color-codes PASS/FAIL
report.add_live_mode_teaser("this analysis")  # VC funding + VMMS/IMMS pitch
report.add_assumptions(["assumption 1", "assumption 2"])
report.build("output/report.html")
```

**Template features**: Inter font, navy/orange brand colors, 8-color chart palette, animated LIVE badge, $500K VC funding badge, CTA mailto link, `@media print` for PDF.

## Lifecycle Utilisation Chart Pattern (Wall Thickness Hero Chart)

The strongest visualization for pipeline demos: a single chart showing utilisation across ALL lifecycle phases with code comparison.

- X-axis: lifecycle phases (Installation, Hydrotest, Operation-Early, Operation-Late, Shutdown)
- Y-axis: utilisation ratio (0 to max, unity line at 1.0)
- Grouped bars: one per design code
- Dropdown selector: pipe size
- Color: green (<0.7), amber (0.7-0.9), red (>0.9)
- Use `create_standard_phases(water_depth, design_pressure)` + `PhaseAnalysisRunner`

This pattern applies to ANY parametric engineering demo -- show utilisation across conditions, not just pass/fail.

## GIF Screencast Pattern (Issue #1809)

Each demo should produce a .gif showing the FULL WORKFLOW:
1. User types natural language prompt in CLI (3s)
2. Agent navigates digitalmodel codebase (5s)
3. Parametric analysis runs with case counter ticking (10s)
4. Report generated message (3s)
5. Browser showing interactive HTML with hover/zoom (10s)

Tool: `vhs` (charmbracelet/vhs) for reproducible scripted terminal GIFs. Target: <5MB, 20-30s, 1024x768.

## Pre-Build Discussion Checklist (MANDATORY)

Before writing any code, resolve these with the user:

1. **Who is the audience?** Cold outreach vs follow-up vs live demo changes everything
2. **What's the sales message?** "Overnight engineering" vs "real-time ops" vs "cost savings"
3. **Engineering rigor level?** Real defensible calcs (slower, credible) vs approximate (faster, less impressive)
4. **Data availability?** Do we have vessel data or need GH issues to collect it?
5. **Branding?** digitalmodel vs aceengineer vs client-specific
6. **Format?** HTML primary + PDF fallback is the proven choice
7. **Chart lineup?** Discuss specific visualisations BEFORE building -- the user will have opinions on what tells the story

The user thinks in terms of "what chart will land the point" not "what data do we have." Start from the chart concept and work backwards to the engineering.

## Lessons Learned

- **Discuss before building**: The user will course-correct the demo scope, format, and chart lineup. Items 3 and 5 were duplicates. The user added "rigid jumper" to item 5 mid-conversation. Discuss FIRST.
- **Build order matters**: Start with demos where modules already exist (wall thickness had full analyzer + parametric sweep + phase analysis). Demos needing new engineering calcs (freespan, catenary) take 2-3x longer.
- **Mid-range WT from catalog gives better demo than minimum WT**: Using minimum standard WT often shows 0.1 utilisation (boring). Mid-range shows variation across 0.2-1.4 (interesting PASS/FAIL mix).
- **FAIL cases are a selling point**: 16"/20" pipes all FAIL at mid-range WT -- this is GOOD for the demo. It shows "you would have caught this overnight." Don't sanitise results to all-PASS.
- **Progress counter is part of the demo**: Print "Case 42/72 | 12in X65 | DNV-ST-F101 | 20 MPa... util=0.716 [PASS]" -- this becomes the GIF content.
- **Binary search for min WT**: Finding minimum required wall thickness uses binary search with 0.1mm tolerance, not brute-force sweep. Much faster.
- **Propagation buckling often governs at 500m+**: At deepwater, collapse/propagation checks drive the design more than pressure containment. The demo should show this insight explicitly.
- **PYTHONPATH setup**: Scripts run with `PYTHONPATH=examples/demos/gtm:src uv run python examples/demos/gtm/demo_XX.py`
- **try/except per case**: Wrap individual parametric cases so one failure doesn't kill the sweep. Record failed cases as N/A in results JSON.
- **First `uv run` takes ~17-20s** for bytecode compilation (32K+ files). Subsequent runs are ~2-3s. Account for this in GIF timing -- either pre-warm or start the GIF after the compile step.
- **Don't let missing vessel data block everything**: Create generic databases immediately, spin GH issues for real data in parallel. The user explicitly said "create databases as needed" rather than wait.

## Reference Implementation

Location: `digitalmodel/examples/demos/gtm/`
- `report_template.py` -- shared HTML builder (GTMReportBuilder class)
- `data/` -- 7 input databases
- `results/` -- 5 output schemas + 2 comparison matrices
- `output/` -- generated HTML reports
- `demo_02_wall_thickness_multicode.py` -- reference demo (1116 lines, 72 cases, 5 charts)
- GitHub tracking: #1800 (master), #1798 (CSV/HLV data), #1799 (pipelay data), #1809 (GIF screencasts)