8.9 KiB
8.9 KiB
description, allowed-tools
| description | allowed-tools |
|---|---|
| velocity | Bash, Read, Edit, Write, Glob, Grep |
velocity
Track team velocity, calculate trends, and forecast completion dates.
Prompt
ROLE: Velocity Analyst & Forecaster
OBJECTIVE Calculate team velocity from completed stories, identify trends, and forecast epic/milestone completion dates.
INPUTS (optional)
- PERIOD=week|sprint|month|all (default: sprint - last 2 weeks)
- FORECAST=<EPIC_ID or milestone> (predict completion date)
- FORMAT=report|chart|json (default: report)
DATA SOURCES
-
Story Completion Data
- docs/09-agents/status.json (current state)
- docs/09-agents/bus/log.jsonl (historical status changes)
- docs/06-stories/**/US-*.md (story estimates and metadata)
-
Epic/Milestone Data
- docs/05-epics/*.md (epic definitions)
- docs/08-project/milestones.md (milestone targets)
VELOCITY CALCULATION
Story Points Completed
Parse bus/log.jsonl for status changes to "done":
{"ts":"2025-10-10T10:00:00Z","type":"status","story":"US-0030","status":"done"}
{"ts":"2025-10-11T14:30:00Z","type":"status","story":"US-0031","status":"done"}
For each story, get estimate from story file frontmatter:
estimate: 1.5d
Convert to points (1d = 1 point) and sum by time period.
Velocity Calculation
Velocity = Total points completed / Number of time periods
Example:
- Week 1: 8 points
- Week 2: 10 points
- Week 3: 7 points
- Average velocity: (8+10+7)/3 = 8.3 points/week
VELOCITY REPORT
# Velocity Report
**Generated**: 2025-10-17 14:30
**Period**: Last 4 sprints (8 weeks)
**Team**: AG-UI, AG-API, AG-CI, AG-DEVOPS
---
## 📊 Current Velocity
**Average**: 8.3 points/week
**Trend**: ↗️ +15% (improving)
**Last sprint**: 10 points
**Best sprint**: 12 points (Week of 2025-09-15)
**Worst sprint**: 5 points (Week of 2025-09-01)
---
## 📈 Historical Velocity
Points 12 │ ● 11 │ ╱ 10 │ ● ● ● 9 │ ╱ ╲ ╱ 8 │ ● ● 7 │ ● 6 │ ╱ 5 │ ● ● 4 │ ╱ 3 │ └──────────────────── W1 W2 W3 W4 W5 W6 W7 W8
Trend line: ─── (moving average) Actual: ● ─ ●
**Weekly Breakdown**:
| Week | Points | Stories | Avg Size | Notes |
|------|--------|---------|----------|-------|
| 2025-10-14 | 10 | 6 | 1.7d | ↗️ +25% |
| 2025-10-07 | 8 | 5 | 1.6d | ↗️ +14% |
| 2025-09-30 | 7 | 4 | 1.8d | ↘️ -30% |
| 2025-09-23 | 10 | 7 | 1.4d | ↗️ +100% |
| 2025-09-16 | 5 | 3 | 1.7d | ↘️ -50% |
| 2025-09-09 | 10 | 6 | 1.7d | - |
**Insights**:
- Velocity is trending upward (+15% over 6 weeks)
- Best performance when story size ≤1.5d
- Week of 2025-09-23 had highest throughput (7 stories)
- Consistency improving (std dev: 2.1 → 1.8)
---
## 👥 Velocity by Owner
| Owner | Points/Week | Stories/Week | Utilization | Trend |
|-------|-------------|--------------|-------------|-------|
| AG-UI | 3.2 | 2.1 | 80% | ↗️ +10% |
| AG-API | 4.1 | 2.8 | 85% | ↗️ +20% |
| AG-CI | 0.8 | 0.6 | 40% | → Stable |
| AG-DEVOPS | 0.2 | 0.2 | 10% | 🆕 New |
**Observations**:
- AG-API is the team workhorse (4.1 pts/wk)
- AG-CI underutilized (consider more stories)
- AG-DEVOPS just started (too early for trends)
---
## 🎯 Forecast: Epic Completion
### EP-0010: User Authentication
- **Stories**: 12 total
- **Completed**: 8 (66%)
- **Remaining**: 4 stories, 6 points
- **At current velocity** (8.3 pts/wk): **< 1 week**
- **Forecast completion**: **2025-10-24** (7 days)
- **Confidence**: High (85%)
### EP-0011: Payment Integration
- **Stories**: 8 total
- **Completed**: 2 (25%)
- **Remaining**: 6 stories, 9 points
- **At current velocity** (8.3 pts/wk): **~1.1 weeks**
- **Forecast completion**: **2025-10-28** (11 days)
- **Confidence**: Medium (70%)
### Milestone: Public Beta Launch
- **Target date**: 2025-11-15
- **Total remaining**: 15 stories, 24 points
- **Weeks needed**: 24/8.3 = **2.9 weeks**
- **Forecast completion**: **2025-11-07** (21 days)
- **Status**: ✅ **On track** (8 days buffer)
- **Risk level**: Low
---
## ⚠️ Risk Analysis
### Velocity Risks
1. **AG-API dependency**: 50% of points from one agent
- *Mitigation*: Cross-train, pair programming
2. **Story size variance**: Some 2d stories slow velocity
- *Mitigation*: Split stories >1.5d
3. **Seasonal slowdown**: Historical dip in Week 5
- *Mitigation*: Add buffer to forecasts
### Schedule Risks
- EP-0011 blocking Milestone: Public Beta
- If velocity drops 20% → Beta delayed to 2025-11-12
- If AG-API unavailable → 50% velocity loss
---
## 📅 Capacity Planning
**Current Capacity**: 8.3 points/week (4 agents)
**Recommendations**:
1. **This Sprint** (2 weeks):
- Plan: 16-18 points (2x velocity)
- Buffer: Keep 2-3 ready stories
- Focus: Complete EP-0010
2. **Next Sprint**:
- Plan: 16-20 points
- Priority: EP-0011 (Beta blocker)
- Consider: Add stories for AG-CI (underutilized)
3. **Long-term**:
- Maintain 8-10 points/week sustained velocity
- Reserve 20% for tech debt (/AgileFlow:tech-debt command)
- Keep story sizes ≤1.5d for predictability
---
## 🎯 Velocity Goals
**Current**: 8.3 points/week
**Target**: 10 points/week (by end of quarter)
**Stretch**: 12 points/week
**Action Items**:
- [ ] Split 2 large stories (US-0050, US-0051)
- [ ] Assign 2 more stories to AG-CI
- [ ] Review blockers (US-0041)
- [ ] Celebrate hitting 10 pts/wk milestone! 🎉
---
## 📊 Export Options
Save this report?
- `docs/08-project/velocity/velocity-2025-10-17.md`
- Update velocity dashboard
- Add to stakeholder update
FORECASTING ALGORITHM
Simple Linear Forecast
Days to complete = (Remaining points / Velocity) * 7
Completion date = Today + Days to complete
Confidence Calculation
Confidence = 100% - (Velocity std dev / Velocity avg) * 100
High confidence: >80% (stable velocity)
Medium: 60-80% (some variance)
Low: <60% (high variance, unreliable)
Monte Carlo Simulation (optional, advanced)
Run 1000 simulations with velocity variance:
For each simulation:
- Sample velocity from normal distribution (mean, std dev)
- Calculate completion date
- Record result
Forecast:
- P50 (median): 50% chance of completing by this date
- P80: 80% chance
- P90: 90% chance (conservative estimate)
VELOCITY CHART (ASCII Art)
Velocity Trend (8 weeks)
Points/Week
12 ┤ ●●●
11 ┤ ●
10 ┤ ●● ●
9 ┤ ● ●
8 ┤ ● ← Current (8.3 avg)
7 ┤ ●
6 ┤ ●
5 ┤ ● ●
4 ┤ ●
3 ┤
└─────────────────────────────────────
W1 W2 W3 W4 W5 W6 W7 W8
Legend:
● Actual velocity
─ Trend line (moving average)
↗️ Trend: +15% over period
VELOCITY BY STORY SIZE
Velocity by Story Size
Size | Count | Avg Days | Success Rate
--------|-------|----------|-------------
≤0.5d | 8 | 0.4d | 100% ✅
0.5-1d | 12 | 0.9d | 92% ✅
1-1.5d | 10 | 1.3d | 80% ⚠️
1.5-2d | 6 | 2.1d | 67% ⚠️
>2d | 3 | 3.5d | 33% 🔴
**Insight**: Stories ≤1d complete faster and more reliably.
**Recommendation**: Split stories >1.5d into smaller increments.
JSON OUTPUT (for tooling)
{
"generated": "2025-10-17T14:30:00Z",
"period": "8 weeks",
"velocity": {
"current": 8.3,
"trend": "+15%",
"last_sprint": 10,
"best": 12,
"worst": 5,
"std_dev": 2.1
},
"by_owner": {
"AG-UI": 3.2,
"AG-API": 4.1,
"AG-CI": 0.8,
"AG-DEVOPS": 0.2
},
"forecasts": [
{
"epic": "EP-0010",
"remaining_points": 6,
"weeks_needed": 0.7,
"completion_date": "2025-10-24",
"confidence": 85
}
],
"risks": [
{
"type": "dependency",
"description": "50% of points from AG-API",
"severity": "medium"
}
]
}
WORKFLOW
- Parse bus/log.jsonl for "done" status changes
- Match stories to estimates from frontmatter
- Group completions by time period (week/sprint)
- Calculate velocity stats (avg, trend, std dev)
- If FORECAST specified:
- Calculate remaining points
- Apply velocity to forecast completion
- Calculate confidence level
- Render report/chart
- Suggest actions based on findings
INTEGRATION
- Save velocity history to docs/08-project/velocity/
- Update /AgileFlow:stakeholder-update with velocity data
- Alert if velocity drops >20% from average
- Suggest sprint planning capacity based on velocity
RULES
- Always calculate over at least 3 time periods (for reliability)
- Warn if sample size too small (<5 stories)
- Exclude outliers (stories >3x avg) from velocity calc
- Account for holidays/time off in forecasts
- Update forecast confidence based on variance
OUTPUT
- Velocity report (markdown/chart/json)
- Trend analysis
- Forecasts for epics/milestones
- Risk analysis
- Action items