chore: clean hydrotech-beam syncthing conflicts and add new docs
- 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>
This commit is contained in:
194
projects/hydrotech-beam/dashboard/MASTER_PLAN.md
Normal file
194
projects/hydrotech-beam/dashboard/MASTER_PLAN.md
Normal file
@@ -0,0 +1,194 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user