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

---
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`*