agileflow 2.30.0

package/src/core/commands/metrics.md

@@ -0,0 +1,530 @@
+---
+description: Analytics dashboard with cycle time and throughput
+allowed-tools: Bash, Read, Edit, Write, Glob, Grep
+---
+
+# metrics
+
+Comprehensive project analytics dashboard with cycle time, lead time, throughput, and trend analysis.
+
+## Prompt
+
+ROLE: Metrics & Analytics Specialist
+
+OBJECTIVE
+Generate comprehensive project metrics from AgileFlow data sources (status.json, bus/log.jsonl, story files) to enable data-driven decision making.
+
+INPUTS (optional)
+- TIMEFRAME=7d|30d|90d|all (default: 30d)
+- EPIC=<EP_ID> (filter by specific epic)
+- OWNER=<AG_*> (filter by agent/owner)
+- FORMAT=ascii|markdown|json|csv (default: ascii)
+- METRIC=cycle-time|lead-time|throughput|all (default: all)
+
+DATA SOURCES
+
+### Primary Sources
+1. **docs/09-agents/bus/log.jsonl** - Event stream with timestamps
+   - Story lifecycle events (created, status changes, completed)
+   - Timestamps for all state transitions
+   - Agent assignments and handoffs
+
+2. **docs/09-agents/status.json** - Current state
+   - Active stories and their statuses
+   - Owner assignments
+   - Last updated timestamps
+
+3. **docs/06-stories/**/US-*.md** - Story metadata
+   - Creation dates (from frontmatter or file mtime)
+   - Estimates vs actuals
+   - Epic relationships
+
+4. **docs/05-epics/*.md** - Epic data
+   - Epic start/end dates
+   - Story rollup
+
+CORE METRICS
+
+### 1. Cycle Time
+**Definition**: Time from "in-progress" to "done" (actual work time)
+
+```bash
+# Extract from bus/log.jsonl
+for story in stories; do
+  start=$(jq -r 'select(.story=="'$story'" and .status=="in-progress") | .ts' bus/log.jsonl | head -1)
+  end=$(jq -r 'select(.story=="'$story'" and .status=="done") | .ts' bus/log.jsonl | head -1)
+
+  cycle_time=$(date_diff $start $end)
+  echo "$story: $cycle_time days"
+done
+
+# Calculate statistics
+avg_cycle_time=$(echo "$cycle_times" | awk '{sum+=$1; count++} END {print sum/count}')
+p50_cycle_time=$(echo "$cycle_times" | sort -n | awk '{a[NR]=$1} END {print a[int(NR/2)]}')
+p85_cycle_time=$(echo "$cycle_times" | sort -n | awk '{a[NR]=$1} END {print a[int(NR*0.85)]}')
+```
+
+**Output**:
+```
+Cycle Time (30 days)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Average:    3.2 days
+Median:     2.5 days
+85th %ile:  5.0 days
+Min:        0.5 days
+Max:        8.0 days
+
+Distribution:
+0-1 days  ████████░░ 8 stories (32%)
+1-3 days  ████████████████░░ 12 stories (48%)
+3-5 days  ████░░ 3 stories (12%)
+5+ days   ██░░ 2 stories (8%)
+```
+
+### 2. Lead Time
+**Definition**: Time from story creation to "done" (total time including waiting)
+
+```bash
+for story in stories; do
+  created=$(stat -f %B docs/06-stories/*/$story.md 2>/dev/null || stat -c %Y docs/06-stories/*/$story.md)
+  completed=$(jq -r 'select(.story=="'$story'" and .status=="done") | .ts' bus/log.jsonl | tail -1)
+
+  lead_time=$(date_diff $created $completed)
+  echo "$story: $lead_time days"
+done
+```
+
+**Output**:
+```
+Lead Time (30 days)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Average:    7.8 days
+Median:     6.0 days
+85th %ile:  12.0 days
+
+Breakdown:
+Waiting (ready):        2.5 days (32%)
+Active (in-progress):   3.2 days (41%)
+Review (in-review):     2.1 days (27%)
+```
+
+### 3. Throughput
+**Definition**: Stories completed per time period
+
+```bash
+# Count stories completed in each week
+for week in weeks; do
+  count=$(jq -r 'select(.status=="done" and .ts >= "'$week_start'" and .ts < "'$week_end'") | .story' bus/log.jsonl | sort -u | wc -l)
+  echo "Week $week: $count stories"
+done
+```
+
+**Output**:
+```
+Throughput (Last 8 Weeks)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Week 1  ████████░░ 8 stories
+Week 2  ██████████░░ 10 stories
+Week 3  ██████░░ 6 stories
+Week 4  ████████████░░ 12 stories  ← Peak
+Week 5  ████████░░ 8 stories
+Week 6  ██████░░ 6 stories
+Week 7  ██████████░░ 10 stories
+Week 8  ████████░░ 8 stories
+
+Average: 8.5 stories/week
+Trend:   ↗ +12% vs previous month
+```
+
+### 4. Work In Progress (WIP)
+**Definition**: Stories currently in-progress or in-review
+
+```bash
+wip_count=$(jq -r '.stories | to_entries[] | select(.value.status == "in-progress" or .value.status == "in-review") | .key' status.json | wc -l)
+wip_limit=6  # 2 per agent * 3 agents
+
+echo "Current WIP: $wip_count / $wip_limit"
+if [ $wip_count -gt $wip_limit ]; then
+  echo "⚠️ WIP limit exceeded! Consider finishing stories before starting new ones."
+fi
+```
+
+**Output**:
+```
+Work In Progress
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Current WIP:  4 / 6 stories (67% capacity)
+Status:       ✅ Within limits
+
+Breakdown:
+  in-progress:  3 stories
+  in-review:    1 story
+  blocked:      0 stories
+
+By Owner:
+  AG-API:  2 stories (at limit)
+  AG-UI:   1 story
+  AG-CI:   1 story
+```
+
+### 5. Agent Utilization
+**Definition**: Distribution of work across agents
+
+```bash
+for agent in AG-UI AG-API AG-CI AG-DEVOPS; do
+  completed=$(jq -r 'select(.status=="done" and .owner=="'$agent'") | .story' bus/log.jsonl | sort -u | wc -l)
+  in_progress=$(jq -r '.stories | to_entries[] | select(.value.owner=="'$agent'" and .value.status=="in-progress") | .key' status.json | wc -l)
+  echo "$agent: $completed done, $in_progress active"
+done
+```
+
+**Output**:
+```
+Agent Utilization (30 days)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+AG-API     ████████████████░░ 12 stories (40%)  2 active
+AG-UI      ████████████░░ 10 stories (33%)      1 active
+AG-CI      ██████░░ 6 stories (20%)             1 active
+AG-DEVOPS  ██░░ 2 stories (7%)                  0 active
+
+Balance Score: 78/100 (Good distribution)
+Recommendation: Consider assigning more work to AG-DEVOPS
+```
+
+### 6. Epic Health
+**Definition**: Progress and health indicators for epics
+
+```bash
+for epic in epics; do
+  total_stories=$(ls docs/06-stories/$epic/*.md | wc -l)
+  done_stories=$(jq -r 'select(.epic=="'$epic'" and .status=="done")' bus/log.jsonl | wc -l)
+  blocked_stories=$(jq -r '.stories | to_entries[] | select(.value.epic=="'$epic'" and .value.status=="blocked") | .key' status.json | wc -l)
+
+  completion_pct=$((done_stories * 100 / total_stories))
+  health="🟢"  # Green
+  [ $blocked_stories -gt 0 ] && health="🟡"  # Yellow
+  [ $completion_pct -lt 30 ] && [ $blocked_stories -gt 1 ] && health="🔴"  # Red
+
+  echo "$epic: $completion_pct% complete, $blocked_stories blocked $health"
+done
+```
+
+**Output**:
+```
+Epic Health
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+EP-0010: Authentication
+  Progress:  ████████████████████░░ 85% (11/13 stories)
+  Status:    🟢 On track
+  Velocity:  2.5 stories/week
+  ETA:       ~1 week
+
+EP-0011: Payment Processing
+  Progress:  ████████░░ 40% (4/10 stories)
+  Status:    🟡 At risk (2 blocked)
+  Velocity:  1.2 stories/week
+  ETA:       ~5 weeks
+  ⚠️ Action: Unblock US-0045, US-0048
+
+EP-0012: User Dashboard
+  Progress:  ██░░ 10% (1/10 stories)
+  Status:    🟢 Healthy
+  Velocity:  0.5 stories/week (just started)
+  ETA:       ~18 weeks
+```
+
+ADVANCED METRICS
+
+### 7. Estimation Accuracy
+**Definition**: Compare estimates vs actual cycle time
+
+```bash
+for story in completed_stories; do
+  estimate=$(grep "^estimate:" docs/06-stories/*/$story.md | awk '{print $2}' | sed 's/d//')
+  actual=$(calculate_cycle_time $story)
+  variance=$((actual - estimate))
+  echo "$story: Est $estimate, Act $actual, Var $variance"
+done
+
+avg_variance=$(echo "$variances" | awk '{sum+=$1; count++} END {print sum/count}')
+```
+
+**Output**:
+```
+Estimation Accuracy
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Average Variance:  +0.5 days (underestimating by 15%)
+
+Distribution:
+Under-estimated  ████████████░░ 12 stories (48%)
+Accurate (±20%)  ████████░░ 8 stories (32%)
+Over-estimated   ████░░ 5 stories (20%)
+
+Worst Offenders:
+  US-0042: Est 2d, Act 5d (+150%)
+  US-0035: Est 1d, Act 3d (+200%)
+
+Best Estimates:
+  US-0038: Est 3d, Act 3d (0%)
+  US-0040: Est 2d, Act 2d (0%)
+
+Recommendation: Increase estimates by ~20% for accuracy
+```
+
+### 8. Blocked Story Analysis
+**Definition**: Identify blocking patterns
+
+```bash
+blocked_stories=$(jq -r '.stories | to_entries[] | select(.value.status=="blocked")' status.json)
+
+for story in blocked_stories; do
+  blocked_duration=$(date_diff $(get_blocked_timestamp $story) $(date +%s))
+  echo "$story: Blocked for $blocked_duration days"
+done
+```
+
+**Output**:
+```
+Blocked Story Analysis
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Currently Blocked: 2 stories
+
+US-0045: Payment gateway integration
+  Blocked:     5 days
+  Reason:      Waiting for API keys
+  Owner:       AG-API
+  Impact:      Blocks EP-0011 (40% complete)
+  Action:      Escalate to product for API access
+
+US-0048: Stripe webhook setup
+  Blocked:     2 days
+  Reason:      Depends on US-0045
+  Owner:       AG-API
+  Impact:      Delays payment epic by 1 week
+  Action:      Can unblock after US-0045
+
+⚠️ Critical: 2 stories blocked > 2 days. Review immediately.
+```
+
+### 9. Flow Efficiency
+**Definition**: Active work time / total lead time
+
+```bash
+for story in stories; do
+  lead_time=$(calculate_lead_time $story)
+  cycle_time=$(calculate_cycle_time $story)
+  flow_efficiency=$((cycle_time * 100 / lead_time))
+  echo "$story: $flow_efficiency% efficiency"
+done
+
+avg_efficiency=$(echo "$efficiencies" | awk '{sum+=$1; count++} END {print sum/count}')
+```
+
+**Output**:
+```
+Flow Efficiency
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Average: 41% (3.2d active / 7.8d total)
+
+Interpretation:
+  Stories spend 59% of time waiting (in 'ready' or 'in-review')
+  Only 41% of time is active work
+
+Breakdown:
+  Ready → In-Progress:  2.5 days avg wait
+  In-Progress → Done:   3.2 days avg work
+  In-Review → Done:     2.1 days avg review
+
+Recommendations:
+  🎯 Reduce "ready" wait time (start stories faster)
+  🎯 Reduce "in-review" time (faster code reviews)
+  Target: >60% flow efficiency
+```
+
+### 10. Cumulative Flow Diagram (CFD)
+**Definition**: Stacked area chart showing story distribution over time
+
+```bash
+# Generate data for each day in timeframe
+for day in $(seq 0 30); do
+  date=$(date -d "$day days ago" +%Y-%m-%d)
+
+  ready=$(count_stories_in_status_on_date "ready" $date)
+  in_progress=$(count_stories_in_status_on_date "in-progress" $date)
+  in_review=$(count_stories_in_status_on_date "in-review" $date)
+  done=$(count_stories_in_status_on_date "done" $date)
+
+  echo "$date $ready $in_progress $in_review $done"
+done
+```
+
+**Output (ASCII visualization)**:
+```
+Cumulative Flow Diagram (Last 30 Days)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+30 │                                      ████████████ Done
+25 │                              ████████████████████
+20 │                      ████████████████████████████
+15 │              ████████████████████████████████████ In Review
+10 │      ████████████████████████████████████████████ In Progress
+ 5 │██████████████████████████████████████████████████ Ready
+ 0 └────────────────────────────────────────────────→
+   Oct 17    Oct 24       Oct 31       Nov 7    Nov 14
+
+Insights:
+  ✅ Steady throughput (done stories increasing linearly)
+  ⚠️ WIP creeping up (in-progress growing)
+  🎯 Review bottleneck (in-review staying constant)
+```
+
+DASHBOARD OUTPUT
+
+### ASCII Dashboard (default)
+```markdown
+╔════════════════════════════════════════════════════════════════╗
+║                    AGILEFLOW METRICS DASHBOARD                  ║
+║                      Last 30 Days (Oct 17 - Nov 14)             ║
+╠════════════════════════════════════════════════════════════════╣
+║                                                                 ║
+║  📊 KEY METRICS                                                 ║
+║  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  ║
+║                                                                 ║
+║  Cycle Time:        3.2 days avg  (↓ 8% vs last month)        ║
+║  Lead Time:         7.8 days avg  (↑ 5% vs last month)        ║
+║  Throughput:        8.5 stories/week  (↗ +12%)                 ║
+║  Flow Efficiency:   41%  (Target: >60%)                        ║
+║                                                                 ║
+║  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  ║
+║                                                                 ║
+║  🎯 WORK IN PROGRESS                                            ║
+║  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  ║
+║                                                                 ║
+║  Current WIP:  4 / 6 stories (67%)  ✅                         ║
+║  Blocked:      2 stories  ⚠️                                   ║
+║                                                                 ║
+║  AG-API:     2 stories (at limit)                              ║
+║  AG-UI:      1 story                                           ║
+║  AG-CI:      1 story                                           ║
+║  AG-DEVOPS:  0 stories                                         ║
+║                                                                 ║
+║  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  ║
+║                                                                 ║
+║  📈 EPIC HEALTH                                                 ║
+║  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  ║
+║                                                                 ║
+║  EP-0010  ████████████████████░░  85%  🟢 On track             ║
+║  EP-0011  ████████░░            40%  🟡 2 blocked              ║
+║  EP-0012  ██░░                  10%  🟢 Healthy                ║
+║                                                                 ║
+║  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  ║
+║                                                                 ║
+║  ⚡ RECOMMENDATIONS                                             ║
+║  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  ║
+║                                                                 ║
+║  1. Unblock US-0045, US-0048 (blocked >2 days)                 ║
+║  2. Reduce review time (currently 2.1 days avg)                ║
+║  3. Assign more stories to AG-DEVOPS (0 active)                ║
+║  4. Improve estimation accuracy (+15% variance)                ║
+║                                                                 ║
+╚════════════════════════════════════════════════════════════════╝
+
+Run `/AgileFlow:velocity` for forecasting
+Run `/AgileFlow:board` for current kanban view
+Run `/AgileFlow:retro` for retrospective insights
+```
+
+EXPORT FORMATS
+
+### JSON Export
+```json
+{
+  "timeframe": "30d",
+  "generated_at": "2025-10-17T15:00:00Z",
+  "metrics": {
+    "cycle_time": {
+      "avg": 3.2,
+      "median": 2.5,
+      "p85": 5.0,
+      "unit": "days",
+      "change_pct": -8
+    },
+    "lead_time": {
+      "avg": 7.8,
+      "median": 6.0,
+      "p85": 12.0,
+      "unit": "days",
+      "change_pct": 5
+    },
+    "throughput": {
+      "avg": 8.5,
+      "unit": "stories/week",
+      "change_pct": 12,
+      "trend": "up"
+    },
+    "wip": {
+      "current": 4,
+      "limit": 6,
+      "pct": 67,
+      "blocked": 2
+    }
+  },
+  "epics": [...],
+  "recommendations": [...]
+}
+```
+
+### CSV Export
+```csv
+Date,Cycle Time,Lead Time,Throughput,WIP,Blocked
+2025-10-17,3.2,7.8,8.5,4,2
+2025-10-16,3.1,7.5,8.2,5,1
+...
+```
+
+USAGE EXAMPLES
+
+### View all metrics for last 30 days
+```bash
+/AgileFlow:metrics
+```
+
+### Last 90 days, specific epic
+```bash
+/AgileFlow:metrics TIMEFRAME=90d EPIC=EP-0010
+```
+
+### Only cycle time, export as JSON
+```bash
+/AgileFlow:metrics METRIC=cycle-time FORMAT=json
+```
+
+### Agent-specific metrics
+```bash
+/AgileFlow:metrics OWNER=AG-API TIMEFRAME=7d
+```
+
+### Export to CSV for spreadsheet analysis
+```bash
+/AgileFlow:metrics FORMAT=csv > metrics.csv
+```
+
+INTEGRATION WITH OTHER COMMANDS
+
+- After `/AgileFlow:velocity`: Run `/AgileFlow:metrics` to see detailed trends
+- After `/AgileFlow:board`: Run `/AgileFlow:metrics` to understand bottlenecks
+- Before `/AgileFlow:retro`: Run `/AgileFlow:metrics` to gather data for retrospective
+- In `/AgileFlow:babysit`: Auto-run `/AgileFlow:metrics` when velocity drops
+
+RULES
+- Always calculate from raw data (bus/log.jsonl, status.json)
+- Show trends (↗↘) compared to previous period
+- Highlight actionable insights
+- Use color coding (🟢🟡🔴) for health indicators
+- Provide recommendations based on data
+- Respect privacy (no individual developer metrics, only agent-level)
+
+OUTPUT
+- ASCII dashboard (default, shown above)
+- Or JSON/CSV/Markdown based on FORMAT parameter
+- Always include timeframe and generation timestamp
+- Save to docs/08-project/metrics-reports/metrics-YYYYMMDD.md (optional)