tegwick
3108094e0a
All 9 tasks done (S1.1–S3.2). llm-connect is now a standalone
installable package at /home/worsch/llm-connect, integrated into
state-hub as its first consumer (S3.1, commit 444b35d).
Also tracks workstream-kpi.md spec (previously untracked).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
7.3 KiB
Workstream Health Index (WHI)
Introduction & Requirements Specification
Status: Draft Purpose: Define a quantitative KPI for structural health, coupling, and flow efficiency of workstreams Scope: Program-level coordination across domains and within domains Primary Audience: Project leads, system architects, program management, AI orchestration agents
1. Problem Statement
Modern complex initiatives consist of multiple concurrent workstreams distributed across teams and domains. Ideally, workstreams should be:
- Independently executable
- Minimally coupled
- Parallelizable
- Robust against delays in other streams
In practice, dependencies emerge due to:
- Architectural constraints
- Resource limitations
- Organizational structure
- Poor decomposition of work
- Hidden prerequisite relationships
Excessive coupling leads to:
- Blocking states
- Cascading delays
- Increased coordination overhead
- Reduced throughput
- Fragile timelines
- Circular waiting situations (deadlocks)
Traditional project metrics (e.g., completion %, velocity, burn-down) do not capture structural health of the work graph.
Therefore, a dedicated metric is required to assess:
How well the program structure supports parallel execution and stable progress.
2. Conceptual Model
Workstreams form a directed dependency graph:
- Nodes = workstreams
- Edges = prerequisite relationships
- Status = operational state
- Domains = logical grouping
Health is determined by:
- Structural coupling (how many dependencies exist)
- Operational blocking (how many streams cannot proceed)
- Concentration of risk (single points of failure)
- Parallel execution potential
- Cross-domain entanglement
- Presence of cycles (deadlocks)
3. Definition: Workstream Health Index (WHI)
The Workstream Health Index (WHI) is a composite KPI representing the overall coordination efficiency and structural soundness of the workstream network.
WHI is normalized to a value in the range:
[ 0 \le WHI \le 1 ]
Where:
- 1.0 = ideal independence
- 0.0 = severe systemic dysfunction
WHI must be computed for:
- Entire program
- Each domain (intra-domain)
- Cross-domain interactions
4. Base Metrics
WHI aggregates the following primary indicators.
4.1 Dependency Density (DD)
Purpose: Measure structural coupling introduced during planning.
[ DD = \frac{\text{Number of dependency edges}}{\text{Number of active + blocked workstreams}} ]
Interpretation:
- Low DD → decomposed, parallelizable work
- High DD → tightly coupled system
Completed and archived streams are excluded because they no longer constrain progress.
4.2 Blocked Ratio (BR)
Purpose: Measure immediate operational impact of dependencies.
[ BR = \frac{\text{Blocked workstreams}}{\text{Active + Blocked workstreams}} ]
Interpretation:
- BR ≈ 0 → flow is unobstructed
- High BR → large portion of work cannot proceed
4.3 Single-Point Risk (SPR)
Purpose: Detect concentration of blocking power.
[ SPR = \frac{\text{Max number of dependents on one incomplete workstream}}{\text{Active + Blocked}} ]
High SPR indicates fragile structure where one delay propagates widely.
4.4 Parallel Execution Potential (PEP)
Purpose: Estimate how much work can proceed immediately.
A workstream is eligible if:
- Status = active
- All dependencies are completed
[ PEP = \frac{\text{Eligible active workstreams}}{\text{Active + Blocked}} ]
4.5 Cross-Domain Dependency Ratio (CDDR)
Purpose: Measure architectural entanglement between domains.
[ CDDR = \frac{\text{Dependencies crossing domain boundaries}}{\text{Total dependencies}} ]
High values indicate loss of modularity.
4.6 Cycle Presence Indicator (CPI)
Purpose: Detect circular dependencies (deadlocks).
CPI =
- 0 → no cycles
- 1 → at least one cycle detected
Any cycle indicates structural invalidity of the dependency graph.
5. WHI Aggregation Formula
Recommended weighted model:
[ WHI = 0.30 \cdot (1 - DD_{norm}) + 0.25 \cdot (1 - BR) + 0.15 \cdot (1 - SPR) + 0.20 \cdot PEP + 0.10 \cdot (1 - CDDR) ]
If CPI = 1 (cycle present):
[ WHI = WHI \times 0.5 ]
This penalty ensures deadlocks strongly degrade health.
Normalization of DD
Because DD is unbounded, normalize using a saturation threshold:
[ DD_{norm} = \min\left(1, \frac{DD}{DD_{critical}}\right) ]
Recommended:
[ DD_{critical} = 1.0 ]
Meaning: one dependency per workstream is considered heavily coupled.
6. Aggregation Across Domains
WHI must be computed at three levels:
6.1 Intra-Domain WHI
Using only workstreams and dependencies within the domain.
Purpose:
- Evaluate domain autonomy
- Identify internal planning issues
6.2 Cross-Domain WHI
Using only dependencies crossing domains.
Purpose:
- Assess integration complexity
- Identify architectural entanglement
6.3 Global WHI
Computed on the full graph.
7. Health States
🟢 GREEN — Healthy Structure
Condition: Workstreams are largely independent and flow is stable.
Recommended thresholds:
- WHI ≥ 0.75
- BR ≤ 0.20
- DD ≤ 0.5
- SPR ≤ 0.25
- No cycles
- PEP ≥ 0.6
Interpretation:
- Parallel execution effective
- Delays localized
- Planning adequate
No intervention required.
🟠 ORANGE — Optimizable Coupling
Condition: Dependencies introduce noticeable coordination cost but system remains viable.
Trigger if ANY of:
- 0.50 ≤ WHI < 0.75
- 0.20 < BR ≤ 0.40
- 0.5 < DD ≤ 1.0
- 0.25 < SPR ≤ 0.40
- PEP between 0.3 and 0.6
- High cross-domain dependencies (> 0.4)
Interpretation:
- Parallelism reduced
- Timeline sensitive to delays
- Replanning likely beneficial
Recommended action:
Review decomposition and dependency structure.
🔴 RED — Critical Coupling / Structural Failure
Condition: Systemic blockage or high fragility.
Trigger if ANY of:
- WHI < 0.50
- BR > 0.40
- DD > 1.0
- SPR > 0.40
- PEP < 0.30
- CPI = 1 (cycle present)
- Large clusters of mutually blocked streams
Interpretation:
- Serial execution dominates
- High coordination overhead
- Cascading delays likely
- Timeline unreliable
Required action:
Immediate optimization at the planning layer.
8. Circular Dependency Handling
Circular dependencies are treated as critical defects because they imply:
- No feasible execution order
- Deadlock or hidden assumptions
- Planning inconsistency
Detection must use graph cycle detection (e.g., DFS or topological sort failure).
9. Recommended Usage
WHI should be used for:
- Program governance dashboards
- Planning reviews
- Architecture decisions
- Early risk detection
- Automated orchestration systems
- AI-assisted planning tools
WHI is not a performance metric for individuals.
10. Design Principles
The metric system is designed to be:
- Domain-agnostic
- Scalable
- Resistant to gaming
- Actionable
- Explainable via drilldown
- Compatible with automated systems
- Suitable for long-lived programs
11. Summary
The Workstream Health Index provides a quantitative measure of how effectively an organization structures work for parallel execution and stable progress.
It captures both:
- Structural design quality
- Operational flow conditions
By combining graph properties with status information, WHI enables proactive management of coordination complexity.