Anto01
ed6874092f
- Remove all .sync-conflict-* files - Remove temp _temp_part_properties.json files - Add USER_GUIDE.md - Add dashboard docs (Executive, Technical, Operations, Master Plan) - Add playbooks (DOE, NX_REAL_RUN, SYNCTHING_RECOVERY) - Update iteration results Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
195 lines
5.5 KiB
Markdown
195 lines
5.5 KiB
Markdown
# 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.
|