Find Delivery Bottleneck Tool
find-delivery-bottleneck-toolWhere does a change spend its waiting time — in the backlog, being written, before review, in review, or after merge? Splits the path from "somebody asked for this" to "shipped to production" into six stages — sitting in the backlog, being written on a branch, waiting for a first review, in review, merged and waiting for a deploy, and the deploy itself running — times each one across recently merged pull requests, and names the single slowest stage with the pull requests that prove it and one intervention to try.
Use this to answer "why is our delivery slow" with one stage instead of five dashboards. The interventions differ completely by stage: chasing reviewers does nothing when the wait is after merge.
A stage is only named as the bottleneck when it was measurable on enough of the window's work. A stage that could barely be seen is still reported, with the reason it is ineligible — so missing deployment tracking reads as missing deployment tracking rather than as a fast deploy. Bot pull requests are excluded. Review history is pruned after 90 days, so the window is clamped there.
The backlog stage is measured and reported but never named as the bottleneck: it is the gap before anybody started rather than a change waiting to move, it dwarfs the delivery stages wherever a tracker is connected, and it answers to prioritisation instead. It is timed from the linked Jira or Linear issue.
The two deploy stages are scored only against repositories that have ever recorded a
production deployment, because a package or a docs site never deploys and counting its
merged work as untracked buries the repositories that do. Each stage carries its own
analysed count for that reason; the repositories left out are named in the blind spots.
A stage that is blank because nothing is connected to time it carries an unlock string —
a tracker for the backlog, a named production environment or deploy reporting for the two
deploy stages — with the full ask in its note. Relay that as something to connect and
what it would reveal, never as a stage with no wait in it: the changes did reach
production, and how long that took is the part nothing can see.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| window_days | No | How many days of merged pull requests to time. Defaults to 30, clamped to 1–90 because review history is pruned after 90 days. | |
| repositories | No | Optional "owner/name" repository slugs to scope to. Leave empty for every active repository the team ships to. Scoping to one representative repository makes the result easier to interpret with a team. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| team | Yes | Team name. | |
| period | Yes | The window actually measured: ISO start, ISO end, and its span in days. | |
| stages | Yes | All six stages — waiting_to_start, writing_the_change, waiting_for_review, in_review, waiting_to_deploy, deploy_running — each with median/p75 hours, sample size, the count it was scored against (`analysed`, which for the two deploy stages counts only repositories that deploy), coverage, whether it is eligible to be ranked, whether it competes for the bottleneck at all (`ranked`, false for waiting_to_start), how many changes merged with no review from anyone but their author and so never entered the stage (`skipped`, review stages only — a skipped change did something, it is not missing data), what would have to be connected to see it (`unlock`), and a note saying why it cannot or will not be ranked. | |
| headline | Yes | One-line answer to lead with when relaying this result. | |
| bottleneck | No | The single slowest eligible stage: median and p75 hours, sample size, coverage, one intervention to try, and the three slowest pull requests as evidence. Null when no stage was measurable on enough of the window — read the stage notes for what is missing. | |
| blind_spots | Yes | What these numbers cannot see. Relay these alongside the finding; the failure mode of this diagnostic is a confident reading of a gap in the data. | |
| repositories | Yes | Repository slugs included in the result. | |
| contributing_factors | Yes | Patterns that make the slowest stage slower — review concentration, oversized changes, current queue pressure, work merging without a recorded review. Reported, never ranked. | |
| pull_requests_analysed | Yes | Human-authored pull requests merged in the window. | |
| unmatched_repositories | Yes | Requested slugs that did not match an active team repository — either not tracked, or archived. |