Metrics on gh-velocity

Lead Time

Mon, 01 Jan 0001 00:00:00 +0000

Lead Time#

Lead time is the total elapsed time from issue creation to closure. It includes time in backlog, waiting for prioritization, blocked by dependencies, in active development, in review, and waiting for release.

Definition#

lead_time = issue.closed_at - issue.created_at

Start signal: issue-created -- the timestamp when the GitHub issue was opened.

End signal: issue-closed -- the timestamp when the issue was closed (by any means: a merged PR, manual close, or bot).

Cycle Time

Mon, 01 Jan 0001 00:00:00 +0000

Cycle Time#

Cycle time measures how long active work took on an issue. Unlike lead time, which includes all waiting time from creation, cycle time starts when work begins.

Two strategies detect when work starts.

What it tells you#

Cycle time reveals how long active work takes, stripped of backlog wait time. A low, consistent cycle time means the team delivers quickly once work begins. High variability suggests inconsistent scope or frequent context-switching.

Velocity

Mon, 01 Jan 0001 00:00:00 +0000

Velocity#

Velocity measures effort completed per iteration (sprint). It tracks how much work finishes each cycle to reveal trends and consistency.

Definition#

velocity = sum(effort) for items completed in the iteration
completion_rate = velocity / committed_effort * 100

Velocity is the total effort of items that are "done" within an iteration.
Committed effort is the total effort of all items assigned to the iteration (done or not).
Completion rate is the percentage of committed effort that was actually completed. If committed effort is 0, completion rate is omitted.

An item is "done" when:

Throughput

Mon, 01 Jan 0001 00:00:00 +0000

Throughput#

Throughput counts issues closed and PRs merged within a time window -- the simplest measure of delivery rate.

Definition#

throughput_issues = count(issues closed in window)
throughput_prs = count(PRs merged in window)

Unweighted: every closed issue and every merged PR counts as 1, regardless of size, complexity, or effort.

Throughput vs. velocity#

Throughput and velocity both measure output, but they differ in two ways:

Dimension	Throughput	Velocity
Weighting	Every item = 1	Items weighted by effort strategy (count, attribute, or numeric)
Time boundary	Arbitrary date range (`--since` / `--until`)	Iteration-aligned (sprint boundaries)

Throughput is useful without sprints or effort estimates. Velocity is useful for tracking effort-weighted output across consistent iteration boundaries.

Quality

Mon, 01 Jan 0001 00:00:00 +0000

Quality Metrics#

Quality metrics analyze the composition and health of a release. They answer: "What did this release contain, and how healthy was the release process?"

What this tells you#

These metrics reveal whether the team is shipping improvements or fighting fires. A rising bug ratio signals growing technical debt. Frequent hotfixes suggest inadequate testing or overly aggressive release schedules. High release lag means finished work sits unreleased, increasing the risk of stale branches and merge conflicts.

Staleness

Mon, 01 Jan 0001 00:00:00 +0000

Staleness#

Staleness measures how recently a work item had activity. It applies to open items in the WIP report.

Signals#

Signal	Threshold	Meaning
ACTIVE	Updated < 3 days ago	Normal activity, no concern
AGING	Updated 3-7 days ago	May need attention
STALE	Updated > 7 days ago	Likely blocked or abandoned

Calculation#

staleness = now - item.updated_at

updated_at is GitHub's last activity timestamp (comments, commits, label changes, status changes)
Thresholds are currently fixed (not configurable)
Staleness is computed at query time, not cached

WIP staleness ratio#

stale_ratio = stale_items / total_wip_items

A high stale ratio (>30%) suggests systemic flow problems -- items are being started but not finished.