Wait-Time Estimation Reference¶

Reference notes for the Jira cycle-time diagnostic script.

Script usage¶

Single issue:

node library/skills/jira-cycle-time-diagnostic/scripts/jira-cycle-time.mjs \
  --issue-key PIPE-1234

Active sprint from board:

node library/skills/jira-cycle-time-diagnostic/scripts/jira-cycle-time.mjs \
  --board-id 9965

JQL slice:

node library/skills/jira-cycle-time-diagnostic/scripts/jira-cycle-time.mjs \
  --jql "project = PIPE AND updated >= -30d ORDER BY updated DESC" \
  --max-issues 150

Deterministic temp output on Unix-like hosts:

node library/skills/jira-cycle-time-diagnostic/scripts/jira-cycle-time.mjs \
  --issue-key PIPE-1234 \
  --out /tmp/jira-cycle-time-diagnostic/output/prm-1234.json

Deterministic temp output in Windows PowerShell:

node library/skills/jira-cycle-time-diagnostic/scripts/jira-cycle-time.mjs `
  --issue-key PIPE-1234 `
  --out "$env:TEMP/jira-cycle-time-diagnostic/output/prm-1234.json"

If the right temp location is unclear for the host or team policy, suggest a default and ask the user to confirm where the output file should live before writing it.

How the estimate works¶

The script estimates flow metrics from issue status history.

flowchart TB
  A[Issue created] --> B{First active status?}
  B -- No --> X[No cycle estimate yet]
  B -- Yes --> C[Cycle start = first time in an active status]
  C --> D[Walk each status interval]
  D --> E{Status in waiting set?}
  E -- Yes --> F[Add interval to wait time]
  E -- No --> G[Do not add interval]
  F --> H{Reached done or resolution date?}
  G --> H
  H -- No --> D
  H -- Yes --> I[Cycle end = first done status or resolution date]
  I --> J[Cycle time = cycle end - cycle start]
  J --> K[Wait pct = wait time / cycle time]

Status sets¶

Active statuses: where cycle time begins, for example In Progress, Development, Doing
Waiting statuses: intervals counted as wait, for example Blocked, Waiting, On Hold
Done statuses: where cycle time ends, for example Done, Closed, Resolved

Formula¶

cycle time = first done timestamp - first active timestamp
wait time = sum of intervals spent in waiting statuses after cycle start
wait % = wait time / cycle time

Worked example (PIPE-675)¶

Use this to sanity-check calculations against one real ticket timeline.

First active status: In Progress at 2026-06-10T02:07:04.545Z
First done status: Done at 2026-06-30T21:44:24.986Z
Waiting segments (status = Blocked):
2026-06-11T22:33:21.803Z to 2026-06-17T22:20:10.494Z = 143.780192 h
2026-06-21T21:24:03.471Z to 2026-06-24T21:09:18.368Z = 71.754138 h
2026-06-29T21:51:41.415Z to 2026-06-29T22:32:13.155Z = 0.675483 h

Computed totals:

cycle time = 499.62234472222224 h
wait time = 216.20981333333333 h
wait % = wait time / cycle time = 0.4327464846544057 (43.274648%)

Timezone cross-check for Jira UI:

Jira shows done at 2026-07-01 09:44 NZ time.
NZST is UTC+12 in July, so Zulu is 2026-06-30T21:44Z, matching the done transition timestamp above.

Where this can be wrong¶

This is only as honest as the workflow discipline behind the status history.

Common undercount cases¶

Work was blocked, but nobody moved the issue into a waiting or blocked state.
Work sat idle in In Progress while people waited on another team, approval, or environment.
Waiting happened before the team first moved the issue into an active status, so it is outside the measured cycle window.

Common overcount cases¶

An issue was moved into a waiting state and left there after work had actually resumed.
Done or resolved dates lagged the real completion time.
The workflow uses a status name as a queue bucket, but people continue working while it sits there.

Common cycle-time distortion cases¶

An issue is moved into In Progress early for planning or intent, not real started work.
Multiple active statuses exist but the configured active set misses the one that marks true start.
Reopened issues are treated as one continuous history instead of separate work episodes.

Interpreting output¶

Treat the result as an operational estimate, not ground truth.
Review a few real tickets against team memory before using the metric for broader claims.
Tune the active, waiting, and done status lists per board or project.
If a team does not reliably use blocked or waiting states, report that as a data quality limitation alongside the percentage.