89 lines
5 KiB
Markdown
89 lines
5 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
|