generated from coulomb/repo-seed
Bernd Worsch
98fb159582
Some checks failed
Test / test (push) Has been cancelled
T01 schema: friction_scores, bottleneck_records, hub_health_snapshots, cross_hub_propagations + migration 1743552000. T02 Widget Pain Heatmap: computeFrictionScore (formula documented), RecomputeFriction action, colour-coded grid view (green/yellow/amber/red). T03 Workflow Bottleneck Analysis: detectBottlenecks across 4 pipeline stages (candidate 30d, requirement 60d, decision 30d, observation 14d), idempotent, severity from age ratio, resolve action. T04 Hub Health Correlation: computeHubHealth (deduction table documented), append-only HubHealthSnapshot, health history view, badge on hub Show page. T05 Cross-Hub Propagation: annotation_cluster + widget_type_friction heuristics, idempotent detection, acknowledge/resolve lifecycle. T06 Operational Review Board: 4-panel AutoRefresh global dashboard — health matrix, top-10 friction, bottleneck stage counts, open propagations. T07 gate: 5 describe blocks in Test/Integration.hs; SCOPE.md updated Phase 7 complete; docs/phase7-summary.md written. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
89 lines
5.0 KiB
Markdown
89 lines
5.0 KiB
Markdown
# IHF Phase 7 Summary — Advanced Observability and Operational Integration
|
||
|
||
## What Was Built
|
||
|
||
Phase 7 turns the accumulated interaction data into operational intelligence. Four new data artifacts and five new views/dashboards give hub leaders a clear picture of where friction is concentrated, where the governance pipeline is stalling, and how hub health is trending over time.
|
||
|
||
### Data Artifacts
|
||
|
||
**FrictionScore** (`friction_scores`)
|
||
- One row per widget (unique constraint on `widget_id`); upserted on recompute
|
||
- Score formula (0–100): `min 100 (annotationCount*5 + errorEventCount*10 + regressionFlag?20:0 + staleCandidateCount*8)`
|
||
- Bands: 0–19 green, 20–39 yellow, 40–59 amber, 60+ red
|
||
- `Application/Helper/FrictionScore.hs` — `computeFrictionScore`, `scoreBand`
|
||
|
||
**BottleneckRecord** (`bottleneck_records`)
|
||
- Detected stalls at four pipeline stages
|
||
- Severity: `medium` → `high` → `critical` based on how far past the threshold
|
||
- `resolved_at` nullable — partial index on `WHERE resolved_at IS NULL` for fast active queries
|
||
- `Application/Helper/BottleneckDetector.hs` — `detectBottlenecks`
|
||
|
||
| Stage | Subject | Threshold |
|
||
|-------|---------|-----------|
|
||
| `candidate` | RequirementCandidate open | 30 days |
|
||
| `requirement` | Requirement without DecisionRecord | 60 days |
|
||
| `decision` | DecisionRecord without DeploymentRecord | 30 days |
|
||
| `observation` | DeploymentRecord without OutcomeSignal | 14 days |
|
||
|
||
**HubHealthSnapshot** (`hub_health_snapshots`)
|
||
- Append-only; every `SnapshotHubHealthAction` inserts a new row
|
||
- Score formula (0–100): `max 0 (100 - openCandidates*5 - regressedWidgets*10 - staleDecisions*8 - criticalBN*12 - highBN*6)`
|
||
- `Application/Helper/HubHealth.hs` — `computeHubHealth`, `healthScoreBadge`
|
||
|
||
**CrossHubPropagation** (`cross_hub_propagations`)
|
||
- Status lifecycle: `open → acknowledged → resolved`
|
||
- `Application/Helper/CrossHubPropagation.hs` — `detectPropagations`
|
||
- Two heuristics:
|
||
- `annotation_cluster`: same annotation category with ≥3 occurrences in ≥2 hubs within 14 days
|
||
- `widget_type_friction`: same widget type with FrictionScore ≥40 in ≥2 hubs
|
||
|
||
### Views and Actions
|
||
|
||
**Friction Heatmap** (`FrictionHeatmapAction { hubId }`)
|
||
- Grid of widget cards, colour-coded by score band
|
||
- "Recompute" button triggers `RecomputeFrictionAction` for all hub widgets
|
||
- Linked from hub Show page as "Friction"
|
||
|
||
**Bottleneck Dashboard** (`BottleneckDashboardAction { hubId }`)
|
||
- Table grouped by pipeline stage; severity badge on each row
|
||
- "Detect" button runs `DetectBottlenecksAction`
|
||
- "Resolve" marks `resolved_at`; idempotent detection skips existing active records
|
||
- Linked from hub Show page as "Bottlenecks"
|
||
|
||
**Hub Health History** (`HubHealthHistoryAction { hubId }`)
|
||
- Latest snapshot shown prominently with component breakdown
|
||
- Full history table in reverse chronological order
|
||
- "Take Snapshot" triggers `SnapshotHubHealthAction`
|
||
- Linked from hub Show page as "Health"
|
||
|
||
**Operational Review Board** (`OperationalReviewBoardAction`)
|
||
- Global view, no hub scope — all hubs, all data
|
||
- Panel 1: Hub health matrix — all hubs, latest score, link to history
|
||
- Panel 2: Top 10 friction widgets across all hubs
|
||
- Panel 3: Active bottleneck counts by pipeline stage
|
||
- Panel 4: Open/acknowledged cross-hub propagation events
|
||
- `autoRefresh` — live-updates
|
||
- Linked from global nav as "Ops Review"
|
||
|
||
**Cross-Hub Propagations** (`CrossHubPropagationsAction`)
|
||
- Global list of all propagation events with status badges
|
||
- "Detect" triggers `DetectPropagationsAction` (idempotent)
|
||
- Acknowledge / Resolve actions per row
|
||
- Linked from global nav as "Propagations"
|
||
|
||
## Known Limitations
|
||
|
||
- **Friction scores are not append-only.** There is no friction history — only the current score per widget. Use `HubHealthSnapshot` for hub-level trends over time.
|
||
- **Bottleneck detection requires manually triggering.** Phase 7 does not introduce scheduled jobs. Detection runs on demand via the UI or `curl`. A future phase can layer on a devenv cron task.
|
||
- **Cross-hub detection requires current friction scores.** Run `RecomputeFrictionAction` on all relevant hubs before `DetectPropagationsAction`, or detection will use stale/absent scores.
|
||
- **OperationalReviewBoard top-10 friction** is sorted globally — not scoped to a hub. A widget from a single hub could dominate the list if that hub has very high friction scores.
|
||
- **`subjectId` in BottleneckRecord is untyped UUID.** The `subject_type` column disambiguates, but there is no FK constraint — subject records can be deleted without cascading. A future phase can add per-stage FK columns.
|
||
|
||
## Phase 8 Readiness
|
||
|
||
Phase 8 (Federated Hub Maturity) can build on Phase 7:
|
||
- `CrossHubPropagation` already models multi-hub patterns; Phase 8 routing can act on these
|
||
- `HubHealthSnapshot` history provides a baseline for measuring federated governance quality
|
||
- The `OperationalReviewBoard` is already global — Phase 8 can add per-organization or per-team scoping
|
||
- Bottleneck thresholds are constants in helper modules — Phase 8 can make them configurable per hub via a `HubPolicy` table
|