Velocity Analysis
Analyze velocity trends and predict capacity for "$ARGUMENTS". Chart historical velocity, calculate statistical measures, correlate changes with events, and recommend sprint commitment ranges.
Arguments. $ARGUMENTS may contain the project name and optional flags. Take the first token as <project> and treat --skip-checks as a flag; never include flags in file paths. All paths below use <project>. If --skip-checks is present, skip the prerequisite check and, before writing any artifact, append one line to .singularskills/log.jsonl: {"ts":"<ISO timestamp>","skill":"project-management-velocity-analysis","workflow":"project-management","phase":4,"project":"<project>","event":"skipped","artifact":"04-improve.md","note":"<reason or \"none given\">"}.
Prerequisites
Part of a workflow. This skill is phase 4 (Improve) of the Scrum workflow (project-management); cross-domain workflows run it too. First check .singularskills/log.jsonl for an open run for this project: a run-started line with "project":"<project>" and no later run-finished line for the same workflow and project. If one exists, the conductor is running you: continue here. Otherwise, if the user asked to start, run, continue or resume a process or workflow rather than this one step, do not continue here: invoke the workflow skill with the workflow the user asked for, or project-management when they named none, followed by <project>; it runs this phase in order, asks before it writes and records the run. Otherwise continue here: a later phase runs on its own, behind its gate.
Run this skill's gate before writing: sh <this skill's folder>/scripts/gate.sh <project> <project root>, where <project root> is the folder that contains .singularskills/ (use . when you are already there). If it exits non-zero, stop and tell the user what it printed, unless --skip-checks was given (see Arguments). On a refusal, before you stop, append this line to .singularskills/log.jsonl (create the folder and file if missing): {"ts":"<ISO timestamp>","skill":"project-management-velocity-analysis","workflow":"project-management","phase":4,"project":"<project>","event":"refused","artifact":"04-improve.md","note":"<what the gate printed>"}. Once the gate has passed, or under --skip-checks once you have appended the skipped line, append this line before you start work: {"ts":"<ISO timestamp>","skill":"project-management-velocity-analysis","workflow":"project-management","phase":4,"project":"<project>","event":"started","artifact":"04-improve.md","note":""}.
Check that .singularskills/project-management/<project>/00-initiate.md exists. If it does not, tell the user to run an Initiate skill first (e.g., project-charter) and stop.
Process
Read existing context:
- Read
.singularskills/project-management/<project>/00-initiate.md for project context, team size, and sprint cadence
- Read
.singularskills/project-management/<project>/03-review.md if it exists (for sprint review results, sprint metrics, and historical velocity data)
- Read
.singularskills/project-management/<project>/04-improve.md if it exists (for retrospective action items and process changes that may have affected velocity)
- Read
.singularskills/project-management/<project>/01-plan.md if it exists (for sprint planning data, committed points, and estimation approach)
- Read
.singularskills/project-management/<project>/02-sprint.md if it exists (for sprint execution data and blocker history)
Chart velocity over last 5-10 sprints:
- Collect completed story points for each of the last 5-10 sprints (or as many as are available)
- Present velocity data as a table: sprint name/number, committed points, completed points, commitment ratio
- Create a text-based chart showing velocity per sprint (horizontal bar chart or similar visualization)
- If fewer than 5 sprints of data are available, note this limitation and adjust analysis accordingly
- Separate velocity into categories if possible: new features, bug fixes, tech debt, unplanned work
Calculate average velocity and standard deviation:
- Calculate the arithmetic mean of completed points across all available sprints
- Calculate the standard deviation to measure velocity consistency
- Calculate the coefficient of variation (standard deviation / mean x 100%) to express variability as a percentage
- Interpret variability:
- < 15% — highly predictable team, estimates are reliable
- 15-30% — normal variability, plan with a range
- > 30% — high variability, investigate causes before relying on velocity for planning
- If available, calculate a weighted moving average (more recent sprints weighted higher) for a more current picture
Identify trends:
- Determine the overall velocity direction: improving, declining, or stable
- Use linear regression direction across the data points to classify the trend:
- Improving — positive slope, team is delivering more over time
- Declining — negative slope, team is delivering less over time
- Stable — slope near zero (within +/- 5% of average), consistent delivery
- If the trend is improving, identify likely causes: team maturity, better estimation, process improvements, reduced tech debt
- If the trend is declining, flag for investigation: team changes, increasing tech debt, morale issues, scope complexity growth
- Note any outlier sprints (more than 2 standard deviations from the mean) and explain them separately
Correlate velocity changes with events:
- Review the project timeline for events that may explain velocity changes:
- Team member changes — new joins (ramp-up period reduces velocity), departures (knowledge loss)
- Holidays and vacations — reduced capacity sprints
- Incidents and outages — unplanned work displacing planned work
- Process changes — new practices from retrospectives or process improvements
- Technical changes — major refactors, platform migrations, new tools
- Map each significant velocity change to its likely cause
- Distinguish between temporary dips (holidays, incidents) and structural shifts (team size change, process change)
- Note which events had the largest impact on velocity and how long recovery took
Calculate sustainable velocity range:
- Define sustainable velocity as the range the team can reliably deliver without burnout
- Calculate the range: average velocity +/- 1 standard deviation
- This gives a low estimate (conservative) and high estimate (optimistic)
- Exclude outlier sprints from the calculation if they were caused by one-time events
- If the team has been consistently above average for 3+ sprints, consider updating the baseline upward
- If the team has been consistently below average, investigate whether the average is still realistic
Predict capacity for next 3 sprints:
- For each of the next 3 sprints, estimate expected capacity:
- Start with the sustainable velocity range
- Adjust for known factors: planned vacations, holidays, team changes, expected incidents
- Express as a range: conservative (low end minus known reductions) to optimistic (high end with ideal conditions)
- Flag any sprints with significantly reduced capacity (holidays, team members out)
- If the team is mid-trend (improving or declining), factor the trend direction into predictions
- Note confidence level for each prediction: high (stable team, good data), medium (some unknowns), low (major changes expected)
Recommend sprint commitment range:
- Based on the analysis, recommend how many story points to commit to in the next sprint
- Provide two numbers:
- Conservative commitment — what the team can almost certainly deliver (low end of sustainable range, rounded down)
- Optimistic commitment — what the team could deliver if everything goes well (average velocity, rounded to nearest whole number)
- Recommend which number to use based on the team's situation:
- Use conservative when: team is rebuilding confidence, new members are ramping up, high-risk work ahead
- Use optimistic when: team is stable and predictable, work is well-understood, team has momentum
- Note that velocity is a planning tool, not a performance metric — do not use it to pressure the team
Write the artifact — append to .singularskills/project-management/<project>/04-improve.md under a ## Velocity Analysis section. Create the file with a # Improve — <project> heading if it does not exist; if a ## Velocity Analysis section already exists, replace only that section. The section contains:
- Velocity History — table and chart of velocity over last 5-10 sprints
- Statistical Summary — average velocity, standard deviation, coefficient of variation
- Trend Analysis — direction (improving/declining/stable) with supporting data
- Event Correlation — velocity changes mapped to team and project events
- Sustainable Velocity Range — calculated range with methodology
- Capacity Predictions — next 3 sprints with expected ranges and confidence levels
- Commitment Recommendation — conservative and optimistic commitment for next sprint with guidance on which to use
Output
Velocity analysis appended to .singularskills/project-management/<project>/04-improve.md. Present a summary highlighting:
- Average velocity and variability (coefficient of variation)
- Trend direction with key contributing factors
- Sustainable velocity range
- Recommended commitment for next sprint (conservative and optimistic)
- Any sprints with reduced capacity in the next 3-sprint window
Record the run. After you have written your section, append this line to .singularskills/log.jsonl (the started line of Prerequisites, with "event":"finished"): {"ts":"<ISO timestamp>","skill":"project-management-velocity-analysis","workflow":"project-management","phase":4,"project":"<project>","event":"finished","artifact":"04-improve.md","note":""}.
This artifact is shared by every skill of phase 4 (Improve). The frontmatter is written once, by whoever creates the file: if you create it, open it with the block below (skill is the phase title, started the time of that first write; gate is passed when the gate ran clean and skipped under --skip-checks); if it already exists, leave the block alone except to update finished and to set gate to the worst value among the sections (skipped over passed).
---
skill: Improve
workflow: project-management
phase: 4
project: <project>
started: <ISO timestamp>
finished: <ISO timestamp>
agent: <the agent you run in, or "unknown">
gate: <passed|skipped>
---
Open your ## Velocity Analysis section with one italic line, *<skill name> · <ISO timestamp> · gate: <passed|skipped>* (your skill name is project-management-velocity-analysis).
End your section with ### Decisions and ### Open questions (one level under your ## Velocity Analysis heading, so the section stays one block), in this shape:
### Decisions
- <what was chosen> — <why> — <what was rejected>
### Open questions
- <what the next phase or a reviewer must settle>
1---2name: project-management-velocity-analysis3description: Analyze velocity over the last 5-10 sprints — average, variability, trend and causes — and forecast a delivery range for the next three. Use when the user has several sprints of history and asks how fast or how predictably the team delivers. Not for one sprint's results or choosing this sprint's stories; see /project-management-sprint-metrics or /project-management-sprint-planning.4metadata:5 source: https://skillmd.com/skills/bromso/project-management-velocity-analysis6 argument-hint: "[project] [--skip-checks]"7 workflow: project-management8 phase: 49 artifact: 04-improve.md10---1112# Velocity Analysis1314Analyze velocity trends and predict capacity for "$ARGUMENTS". Chart historical velocity, calculate statistical measures, correlate changes with events, and recommend sprint commitment ranges.1516**Arguments.** `$ARGUMENTS` may contain the project name and optional flags. Take the first token as `<project>` and treat `--skip-checks` as a flag; never include flags in file paths. All paths below use `<project>`. If `--skip-checks` is present, skip the prerequisite check and, **before writing any artifact**, append one line to `.singularskills/log.jsonl`: `{"ts":"<ISO timestamp>","skill":"project-management-velocity-analysis","workflow":"project-management","phase":4,"project":"<project>","event":"skipped","artifact":"04-improve.md","note":"<reason or \"none given\">"}`.1718## Prerequisites1920**Part of a workflow.** This skill is phase 4 (Improve) of the Scrum workflow (`project-management`); cross-domain workflows run it too. First check `.singularskills/log.jsonl` for an open run for this project: a `run-started` line with `"project":"<project>"` and no later `run-finished` line for the same `workflow` and `project`. If one exists, the conductor is running you: continue here. Otherwise, if the user asked to start, run, continue or resume a process or workflow rather than this one step, do not continue here: invoke the `workflow` skill with the workflow the user asked for, or `project-management` when they named none, followed by `<project>`; it runs this phase in order, asks before it writes and records the run. Otherwise continue here: a later phase runs on its own, behind its gate.2122Run this skill's gate before writing: `sh <this skill's folder>/scripts/gate.sh <project> <project root>`, where `<project root>` is the folder that contains `.singularskills/` (use `.` when you are already there). If it exits non-zero, stop and tell the user what it printed, unless `--skip-checks` was given (see Arguments). On a refusal, before you stop, append this line to `.singularskills/log.jsonl` (create the folder and file if missing): `{"ts":"<ISO timestamp>","skill":"project-management-velocity-analysis","workflow":"project-management","phase":4,"project":"<project>","event":"refused","artifact":"04-improve.md","note":"<what the gate printed>"}`. Once the gate has passed, or under `--skip-checks` once you have appended the `skipped` line, append this line before you start work: `{"ts":"<ISO timestamp>","skill":"project-management-velocity-analysis","workflow":"project-management","phase":4,"project":"<project>","event":"started","artifact":"04-improve.md","note":""}`.2324Check that `.singularskills/project-management/<project>/00-initiate.md` exists. If it does not, tell the user to run an Initiate skill first (e.g., project-charter) and stop.2526## Process27281. **Read existing context:**29 - Read `.singularskills/project-management/<project>/00-initiate.md` for project context, team size, and sprint cadence30 - Read `.singularskills/project-management/<project>/03-review.md` if it exists (for sprint review results, sprint metrics, and historical velocity data)31 - Read `.singularskills/project-management/<project>/04-improve.md` if it exists (for retrospective action items and process changes that may have affected velocity)32 - Read `.singularskills/project-management/<project>/01-plan.md` if it exists (for sprint planning data, committed points, and estimation approach)33 - Read `.singularskills/project-management/<project>/02-sprint.md` if it exists (for sprint execution data and blocker history)34352. **Chart velocity over last 5-10 sprints:**36 - Collect completed story points for each of the last 5-10 sprints (or as many as are available)37 - Present velocity data as a table: sprint name/number, committed points, completed points, commitment ratio38 - Create a text-based chart showing velocity per sprint (horizontal bar chart or similar visualization)39 - If fewer than 5 sprints of data are available, note this limitation and adjust analysis accordingly40 - Separate velocity into categories if possible: new features, bug fixes, tech debt, unplanned work41423. **Calculate average velocity and standard deviation:**43 - Calculate the arithmetic mean of completed points across all available sprints44 - Calculate the standard deviation to measure velocity consistency45 - Calculate the coefficient of variation (standard deviation / mean x 100%) to express variability as a percentage46 - Interpret variability:47 - **< 15%** — highly predictable team, estimates are reliable48 - **15-30%** — normal variability, plan with a range49 - **> 30%** — high variability, investigate causes before relying on velocity for planning50 - If available, calculate a weighted moving average (more recent sprints weighted higher) for a more current picture51524. **Identify trends:**53 - Determine the overall velocity direction: improving, declining, or stable54 - Use linear regression direction across the data points to classify the trend:55 - **Improving** — positive slope, team is delivering more over time56 - **Declining** — negative slope, team is delivering less over time57 - **Stable** — slope near zero (within +/- 5% of average), consistent delivery58 - If the trend is improving, identify likely causes: team maturity, better estimation, process improvements, reduced tech debt59 - If the trend is declining, flag for investigation: team changes, increasing tech debt, morale issues, scope complexity growth60 - Note any outlier sprints (more than 2 standard deviations from the mean) and explain them separately61625. **Correlate velocity changes with events:**63 - Review the project timeline for events that may explain velocity changes:64 - **Team member changes** — new joins (ramp-up period reduces velocity), departures (knowledge loss)65 - **Holidays and vacations** — reduced capacity sprints66 - **Incidents and outages** — unplanned work displacing planned work67 - **Process changes** — new practices from retrospectives or process improvements68 - **Technical changes** — major refactors, platform migrations, new tools69 - Map each significant velocity change to its likely cause70 - Distinguish between temporary dips (holidays, incidents) and structural shifts (team size change, process change)71 - Note which events had the largest impact on velocity and how long recovery took72736. **Calculate sustainable velocity range:**74 - Define sustainable velocity as the range the team can reliably deliver without burnout75 - Calculate the range: average velocity +/- 1 standard deviation76 - This gives a low estimate (conservative) and high estimate (optimistic)77 - Exclude outlier sprints from the calculation if they were caused by one-time events78 - If the team has been consistently above average for 3+ sprints, consider updating the baseline upward79 - If the team has been consistently below average, investigate whether the average is still realistic80817. **Predict capacity for next 3 sprints:**82 - For each of the next 3 sprints, estimate expected capacity:83 - Start with the sustainable velocity range84 - Adjust for known factors: planned vacations, holidays, team changes, expected incidents85 - Express as a range: conservative (low end minus known reductions) to optimistic (high end with ideal conditions)86 - Flag any sprints with significantly reduced capacity (holidays, team members out)87 - If the team is mid-trend (improving or declining), factor the trend direction into predictions88 - Note confidence level for each prediction: high (stable team, good data), medium (some unknowns), low (major changes expected)89908. **Recommend sprint commitment range:**91 - Based on the analysis, recommend how many story points to commit to in the next sprint92 - Provide two numbers:93 - **Conservative commitment** — what the team can almost certainly deliver (low end of sustainable range, rounded down)94 - **Optimistic commitment** — what the team could deliver if everything goes well (average velocity, rounded to nearest whole number)95 - Recommend which number to use based on the team's situation:96 - Use conservative when: team is rebuilding confidence, new members are ramping up, high-risk work ahead97 - Use optimistic when: team is stable and predictable, work is well-understood, team has momentum98 - Note that velocity is a planning tool, not a performance metric — do not use it to pressure the team991009. **Write the artifact** — append to `.singularskills/project-management/<project>/04-improve.md` under a `## Velocity Analysis` section. Create the file with a `# Improve — <project>` heading if it does not exist; if a `## Velocity Analysis` section already exists, replace only that section. The section contains:101 - **Velocity History** — table and chart of velocity over last 5-10 sprints102 - **Statistical Summary** — average velocity, standard deviation, coefficient of variation103 - **Trend Analysis** — direction (improving/declining/stable) with supporting data104 - **Event Correlation** — velocity changes mapped to team and project events105 - **Sustainable Velocity Range** — calculated range with methodology106 - **Capacity Predictions** — next 3 sprints with expected ranges and confidence levels107 - **Commitment Recommendation** — conservative and optimistic commitment for next sprint with guidance on which to use108109## Output110111Velocity analysis appended to `.singularskills/project-management/<project>/04-improve.md`. Present a summary highlighting:112- Average velocity and variability (coefficient of variation)113- Trend direction with key contributing factors114- Sustainable velocity range115- Recommended commitment for next sprint (conservative and optimistic)116- Any sprints with reduced capacity in the next 3-sprint window117118**Record the run.** After you have written your section, append this line to `.singularskills/log.jsonl` (the `started` line of Prerequisites, with `"event":"finished"`): `{"ts":"<ISO timestamp>","skill":"project-management-velocity-analysis","workflow":"project-management","phase":4,"project":"<project>","event":"finished","artifact":"04-improve.md","note":""}`.119120This artifact is shared by every skill of phase 4 (Improve). The frontmatter is written once, by whoever creates the file: if you create it, open it with the block below (`skill` is the phase title, `started` the time of that first write; `gate` is `passed` when the gate ran clean and `skipped` under `--skip-checks`); if it already exists, leave the block alone except to update `finished` and to set `gate` to the worst value among the sections (`skipped` over `passed`).121122```yaml123---124skill: Improve125workflow: project-management126phase: 4127project: <project>128started: <ISO timestamp>129finished: <ISO timestamp>130agent: <the agent you run in, or "unknown">131gate: <passed|skipped>132---133```134135Open your `## Velocity Analysis` section with one italic line, `*<skill name> · <ISO timestamp> · gate: <passed|skipped>*` (your skill name is `project-management-velocity-analysis`).136137End your section with `### Decisions` and `### Open questions` (one level under your `## Velocity Analysis` heading, so the section stays one block), in this shape:138139```markdown140### Decisions141- <what was chosen> — <why> — <what was rejected>142143### Open questions144- <what the next phase or a reviewer must settle>145```