state-hub/dashboard/src/docs/workstream-health-index.md

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 = ready or active workstreams with all deps finished / (ready + active + blocked)

Estimates how much work can proceed right now. A workstream is eligible if its stored workstation label is ready or active and the flow/dependency checks report no unmet dependency assertion; practically, every workstream it depends on has reached finished 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 finished 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