531 lines
19 KiB
Markdown
531 lines
19 KiB
Markdown
---
|
|
description: metrics
|
|
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)
|