Atomizer/projects/hydrotech-beam/dashboard/MASTER_PLAN.md

Hydrotech Beam — Dashboard & Reporting Master Plan (Multi-LLM Synthesis)

Purpose

Give Antoine a single, reliable command view of project health while preserving full technical depth and operational traceability.

This plan synthesizes recommendations from:

• Codex 5.3 (execution architecture + contracts + KPI gates)
• Opus 4.6 (PKM-first, markdown-native, low-overhead governance)
• Gemini Pro (clear role-based dashboards + event-stream discipline)

---

North-Star Architecture (Hybrid, future-proof)

Phase 1 default (now): PKM-native dashboards in markdown

• No new infrastructure required
• Fastest path to value
• Agent-native read/write and auditability

Phase 2+ extension: optional web UI over same contracts

• If/when needed for richer visual analytics
• No rewrite: UI reads the same structured contracts and event logs

Key principle: Data contracts first, presentation second.

---

1) Information Architecture

A. Project-specific (lives under projects/hydrotech-beam/)

• dashboard/ — generated dashboard markdown snapshots
• reports/ — run/phase/executive reports
• runs/ — run manifests and execution metadata
• decisions/ — append-only decision records
• incidents/ — sync/solver/process incident records
• playbooks/ — project execution procedures

B. Foundational (lives under docs/)

• docs/guides/ — reusable dashboard/report standards
• docs/reference/data-contracts/ — versioned schema definitions
• docs/protocols/ — gates, QA, governance rules
• docs/templates/ — report and dashboard templates

---

2) Dashboard Modules (3-tier)

A. Executive Dashboard (60-second scan)

• Project status (RAG + phase + blockers)
• Milestone confidence and slip risk
• Decision hotlist (items needing CEO approval)
• Top risks + mitigation owners
• Gate state (Pass / Conditional / Fail)

B. Technical Dashboard

• DOE/TPE performance (success, feasible points, convergence)
• Constraint panel (disp/stress/geo violations)
• Data quality checks (NaN, stub-vs-nxopen, stale/mixed runs)
• Traceability (requirement → run → result → decision)

C. Operations Dashboard

• Queue and throughput (WIP, cycle time, backlog)
• Blocker tracker + MTTR
• Review SLA status
• Syncthing/data integrity panel
• Documentation freshness/compliance

---

3) Data Contracts (mandatory)

All dashboard/report content must come from structured records with lineage.

Required contracts (v1):

1. run_manifest.v1.json
2. trial_result.v1.json
3. study_summary.v1.json
4. decision_record.v1.json
5. risk_record.v1.json
6. gate_evaluation.v1.json
7. incident_record.v1.json

Required fields in every record:

• schema_version, project_id, run_id (if applicable)
• timestamp_utc, owner, source_file, source_hash

Ingestion rules:

• Reject invalid schema
• Keep append-only history for decisions/gates/incidents
• Nightly integrity check + drift report

---

4) Report System

A. Daily Ops Brief (auto)

• Blockers, failures, overdue reviews, data integrity warnings

B. Weekly Executive Brief (auto + curated)

• Milestone confidence, top risks, decision asks, KPI trend deltas

C. Gate Review Pack (formal)

• Criteria checklist, evidence index, exceptions, sign-offs

D. Technical Deep Dive (on-demand)

• Methods, assumptions, sensitivity, reproducibility evidence

Render path:

• Markdown source of truth
• Optional HTML/PDF exports from templates
• Immutable snapshot ID per issued report

---

5) Governance & Ownership

• Manager (owner): documentation architecture, dashboard governance, release quality
• Tech Lead: technical KPI definitions, thresholds, validation logic
• Study Builder: data pipeline and generators
• Optimizer: analytics logic and recommendation layer
• Auditor: contract compliance + gate QA

Rule enforced:

• Project-specific content in projects/...
• Foundational content in docs/...

---

6) KPI Set + Gate Rules (starter)

KPI starter set

• Solve success rate
• Full feasibility rate
• Best feasible mass
• Constraint violation percentiles (disp/stress)
• Data integrity score
• Decision cycle time
• Blocker MTTR
• Documentation freshness lag

Gate policy

• Gate states: PASS | CONDITIONAL_PASS | FAIL
• Conditional pass requires named owner + due date + risk acceptance
• Hard fail blocks progression

DOE→TPE gate (initial):

• Solve success ≥ 80%
• Feasible points ≥ 5
• Data integrity score ≥ 95%

---

7) Rollout Plan

Phase 0 (48h)

• Contract definitions + KPI dictionary
• Dashboard markdown templates
• Run manifest/logger enabled

Phase 1 (1 week)

• Live executive + operations dashboards
• Daily ops brief + weekly executive brief

Phase 2 (2–3 weeks)

• Technical dashboard depth (DOE/TPE analytics, traceability)
• Gate review packs with evidence linking

Phase 3 (ongoing)

• Optional web UI layer
• Predictive risk signals and anomaly detection

---

8) Risks & Mitigations

1. Backend confusion (stub vs nxopen)

• Mitigation: manifest hard-check + dashboard alert

2. Syncthing conflicts / stale truth

• Mitigation: conflict detector + incident workflow

3. Schema drift

• Mitigation: versioned contracts + validator + auditor checks

4. Dashboard sprawl

• Mitigation: role-based views + KPI change control

5. Documentation decay

• Mitigation: freshness SLA + automated stale flags

---

Decision

Proceed with PKM-native dashboard/report system now, built on strict contracts and governance, with a clean upgrade path to richer UI later.