workflow-health

# /workflow-health — Workflow Health Dashboard

**Purpose**: Aggregate metrics across all completed epics to show workflow system health, velocity trends, and continuous improvement effectiveness.

**Command**: `/workflow-health [--detailed | --trends | --compare]`

**When to use**:

- Check workflow system health across all epics
- Identify velocity trends over time
- Measure ROI of workflow improvements
- Compare epic performance

---

<instructions>

## Workflow Health Analysis

### Step 1: Discover Completed Epics

**Scan for all epic workspaces:**

```bash
EPIC_DIRS=$(find epics -maxdepth 1 -type d -name '[0-9]*' | sort)
EPIC_COUNT=$(echo "$EPIC_DIRS" | wc -l)
```

**Filter for completed epics:**

```bash
COMPLETED_EPICS=()
for dir in $EPIC_DIRS; do
  if grep -q "status: completed" "$dir/state.yaml"; then
    COMPLETED_EPICS+=("$dir")
  fi
done

COMPLETED_COUNT=${#COMPLETED_EPICS[@]}
```

### Step 2: Aggregate Core Metrics

**For each completed epic, extract:**

```javascript
const epicMetrics = [];

for (const epicDir of completedEpics) {
  const state = readYAML(`${epicDir}/state.yaml`);
  const audit = readXML(`${epicDir}/audit-report.xml`); // if exists
  const walkthrough = readXML(`${epicDir}/walkthrough.md`); // if exists

  epicMetrics.push({
    number: extractNumber(epicDir),
    slug: extractSlug(epicDir),
    start_date: state.created_at,
    end_date: state.completed_at,
    duration_hours: calculateDuration(state),
    velocity_multiplier: audit?.velocity_impact?.actual_multiplier || "N/A",
    sprint_count: state.sprints?.length || 0,
    tasks_completed: state.tasks_completed || 0,
    quality_score: audit?.overall_score || "N/A",
    improvements_applied: countHealingReports(epicDir),
  });
}
```

### Step 3: Calculate Aggregate Statistics

**Velocity trends:**

```javascript
const velocityStats = {
  average: calculateAverage(epicMetrics.map((e) => e.velocity_multiplier)),
  trend: calculateTrend(epicMetrics.map((e) => e.velocity_multiplier)),
  best: Math.max(...epicMetrics.map((e) => e.velocity_multiplier)),
  worst: Math.min(...epicMetrics.map((e) => e.velocity_multiplier)),
};

// Trend calculation
// Positive = improving over time
// Negative = degrading over time
const trend = linearRegression(
  epicMetrics.map((e, i) => ({ x: i, y: e.velocity_multiplier }))
).slope;
```

**Quality trends:**

```javascript
const qualityStats = {
  average: calculateAverage(epicMetrics.map((e) => e.quality_score)),
  trend: calculateTrend(epicMetrics.map((e) => e.quality_score)),
  passing_rate:
    epicMetrics.filter((e) => e.quality_score >= 80).length /
    epicMetrics.length,
};
```

**Duration trends:**

```javascript
const durationStats = {
  average_hours: calculateAverage(epicMetrics.map((e) => e.duration_hours)),
  trend: calculateTrend(epicMetrics.map((e) => e.duration_hours)),
  total_hours: sum(epicMetrics.map((e) => e.duration_hours)),
};
```

**Improvement effectiveness:**

```javascript
const improvementStats = {
  total_improvements_applied: sum(
    epicMetrics.map((e) => e.improvements_applied)
  ),
  average_per_epic: calculateAverage(
    epicMetrics.map((e) => e.improvements_applied)
  ),
  epics_with_improvements: epicMetrics.filter((e) => e.improvements_applied > 0)
    .length,
};
```

### Step 4: Display Dashboard

**Default view (summary):**

```
Workflow Health Dashboard
═══════════════════════════════════════════════════════════════

📊 OVERVIEW
────────────────────────────────────────────────────────────────
Total Epics Completed: 5
Total Work Hours: 180h
Average Epic Duration: 36h
Total Improvements Applied: 12

🚀 VELOCITY
────────────────────────────────────────────────────────────────
Average Velocity Multiplier: 3.6x
Best: 4.5x (003-dashboard-epic)
Worst: 2.8x (001-auth-epic)
Trend: ↗ +0.3x per epic (improving)

✅ QUALITY
────────────────────────────────────────────────────────────────
Average Quality Score: 87/100 (B+)
Passing Rate (≥80): 100% (5/5)
Trend: ↗ +2 points per epic (improving)

⏱️ DURATION
────────────────────────────────────────────────────────────────
Average Duration: 36h
Trend: ↘ -4h per epic (improving)

Epic Timeline:
001-auth-epic       ████████████████████ 48h (v3.2x, q85)
002-payments-epic   ████████████████     40h (v3.5x, q86)
003-dashboard-epic  █████████████        32h (v4.5x, q90)
004-api-v2-epic     ████████████         30h (v3.8x, q88)
005-notifications   ██████████           24h (v4.0x, q89)

🔧 CONTINUOUS IMPROVEMENT
────────────────────────────────────────────────────────────────
Improvements Applied: 12 total (2.4 avg per epic)
Epics with Improvements: 5/5 (100%)

Improvement Categories:
  Phase modifications:    5 (42%)
  Gate adjustments:       3 (25%)
  Custom skills:          2 (17%)
  Config changes:         2 (17%)

ROI: High (avg 2.5h saved per epic per improvement)

📈 TRENDS SUMMARY
────────────────────────────────────────────────────────────────
✓ Velocity:   Improving (+0.3x per epic)
✓ Quality:    Improving (+2 pts per epic)
✓ Duration:   Improving (-4h per epic)
✓ Adoption:   100% of epics using workflow

Health Status: ✅ HEALTHY

────────────────────────────────────────────────────────────────
Run with --detailed for per-epic breakdown
Run with --trends for historical charts
Run with --compare to compare epic performance
```

### Step 5: Detailed View (--detailed flag)

**Per-epic breakdown:**

```
Epic Detailed Analysis
═══════════════════════════════════════════════════════════════

001: auth-epic
────────────────────────────────────────────────────────────────
Duration: 48h (2025-11-01 to 2025-11-03)
Sprints: 3 (S01, S02, S03)
Tasks: 28 completed
Velocity: 3.2x (below avg 3.6x)
Quality: 85/100 (B, below avg 87)

Phase Breakdown:
  Specification:    2.0h  (4.2%)
  Clarification:    1.5h  (3.1%)
  Planning:         3.0h  (6.2%)
  Tasks:            0.5h  (1.0%)
  Implementation:   38h   (79.2%) ← bottleneck
  Optimization:     2.0h  (4.2%)
  Preview:          1.0h  (2.1%)

Bottlenecks:
  ⚠ Imple