Files

tegwick efd13b13dd Implement Workstream Health Index (WHI) KPI card

Add a live WHI card to the Workstreams page TOC sidebar. All six base
metrics from the spec (workstream-kpi.md) computed client-side from
existing data — no API or schema changes required.

Computation (workstreams.md):
- DD: dependency edges / open workstreams (normalised at DD_crit=1.0)
- BR: blocked workstreams / open workstreams
- SPR: max inbound deps on one incomplete workstream / open count
- PEP: active workstreams with all deps completed / open count
- CDDR: cross-domain edges / total edges
- CPI: DFS cycle detection (back-edge = 1, halves WHI as hard penalty)
- WHI = 0.30(1-DDnorm) + 0.25(1-BR) + 0.15(1-SPR) + 0.20·PEP + 0.10(1-CDDR)
- Per-domain breakdown using intra-domain edges only

Card UI: global WHI % with green/orange/red health label, sub-metric
rows with per-spec warning thresholds, cycle alert panel, per-domain
breakdown rows with coloured dots.

Also add src/docs/workstream-health-index.md reference page (formula,
thresholds, improvement guidance) and wire ? button on the card.
Add "Workstream Health" to Reference nav.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-02-27 00:03:27 +01:00

4.6 KiB

Raw Blame History

title

title
Workstream Health Index — Reference

Workstream Health Index (WHI)

The Workstream Health Index is a composite score in the range [0, 1] that measures how well the workstream network is structured for parallel execution and stable progress. It is displayed as a live KPI card in the right margin of the Workstreams page and recomputes on every poll (every 15 seconds).

1.0 = ideal independence · 0.0 = severe systemic dysfunction

Health states

Score	Color	Label	Meaning
≥ 0.75	🟢 green	Healthy	Parallel execution effective, delays localized
0.50 – 0.74	🟠 orange	Optimizable	Noticeable coordination cost; review decomposition
< 0.50	🔴 red	Critical	Serial execution dominates; immediate replanning required

The six base metrics

DD — Dependency Density

DD = total dependency edges / (active + blocked workstreams)

Measures structural coupling. Low DD means independent, parallelizable work. Completed and archived workstreams are excluded — they no longer constrain progress.

DD	Warning
> 1.0	🔴 red — more than one dependency per workstream on average
0.5 – 1.0	🟠 orange
≤ 0.5	ok

BR — Blocked Ratio

BR = blocked workstreams / (active + blocked workstreams)

Measures immediate operational impact. BR ≈ 0 means flow is unobstructed.

BR	Warning
> 40%	🔴 red
20–40%	🟠 orange
≤ 20%	ok

SPR — Single-Point Risk

SPR = max dependents on one incomplete workstream / (active + blocked)

Detects concentration of blocking power. High SPR means one delay propagates widely — a structural SPOF.

SPR	Warning
> 40%	🔴 red
25–40%	🟠 orange
≤ 25%	ok

PEP — Parallel Execution Potential

PEP = active workstreams with all deps completed / (active + blocked)

Estimates how much work can proceed right now. A workstream is eligible if its status is active and every workstream it depends on has reached completed or archived.

PEP	Warning
< 30%	🔴 red
30–60%	🟠 orange
≥ 60%	ok

CDDR — Cross-Domain Dependency Ratio

CDDR = dependency edges crossing domain boundaries / total edges

Measures architectural entanglement. High CDDR indicates loss of modularity across the six project domains.

CDDR	Warning
> 40%	🟠 orange

CPI — Cycle Presence Indicator

CPI = 0  →  no cycles
CPI = 1  →  at least one circular dependency detected

Detected via DFS with inStack colouring. Any cycle means no feasible execution order exists — a structural deadlock. When CPI = 1, the final WHI score is halved as a hard penalty.

Aggregation formula

DDnorm = min(1, DD / 1.0)          ← saturates at DD_critical = 1.0

WHI = 0.30 × (1 − DDnorm)
    + 0.25 × (1 − BR)
    + 0.15 × (1 − SPR)
    + 0.20 × PEP
    + 0.10 × (1 − CDDR)

if CPI = 1:  WHI = WHI × 0.5

Result is clamped to [0, 1].

Domain breakdown

The card also shows a per-domain WHI computed using intra-domain workstreams and intra-domain edges only. This measures each domain's internal autonomy — how well its workstreams are decomposed relative to each other, independent of cross-domain dependencies.

A domain with WHI = 100% is fully self-contained and parallelizable internally. Its global contribution to the program-level WHI may still be reduced by cross-domain dependencies (captured in CDDR).

The domain breakdown is shown when at least two domains have active workstreams.

How to improve a poor score

Symptom	Action
High DD	Decompose tightly coupled workstreams; remove unnecessary dependencies
High BR	Unblock workstreams — resolve the blocking condition, or mark dependency as completed if done
High SPR	Split the bottleneck workstream into independent deliverables
Low PEP	Complete prerequisite workstreams or re-sequence work
High CDDR	Refactor cross-domain dependencies into shared contracts or invert the dependency
CPI = 1	Find and break the cycle — identify which dependency edge is incorrect and remove it

What WHI is not

WHI measures structural health of the work graph — not individual performance, not velocity, not burn-down rate. A team can be moving fast with a poor WHI (serially but quickly), or slowly with a perfect WHI (fully parallel but under-resourced). Use WHI alongside velocity metrics, not instead of them.

Specification: state-hub/dashboard/src/docs/workstream-kpi.md

4.6 KiB Raw Blame History Unescape Escape