Skip to content

Jira Cycle-Time Diagnostic

ContributorsMyles Henaghan

Contributors 🕹️ Myles Henaghan

When to use: Build a deterministic issue-history extract from Jira so you can estimate cycle time and waiting/blocking share for one ticket, an active sprint, or a JQL slice.

Intent

Use this skill when you need delivery-flow diagnostics from Jira state transitions. It fetches issue changelogs and computes:

  • Estimated cycle time (hours)
  • Waiting/blocking time (hours)
  • Waiting share of cycle time (%)

Scope confirmation first

Before running commands, confirm these values with the user:

  • Target board (if sprint mode)
  • Target issue(s) or JQL
  • Waiting statuses to count (for example Blocked, Waiting, On Hold)
  • Active-work statuses to start cycle timing (for example In Progress, Development)
  • Done statuses to end cycle timing (for example Done, Closed, Resolved)

Script path

  • library/skills/jira-cycle-time-diagnostic/scripts/jira-cycle-time.mjs

Local environment

Put credentials in a local .env file at repo root (gitignored):

  • JIRA_BASE_URL
  • JIRA_EMAIL
  • JIRA_API_TOKEN
  • JIRA_BOARD_ID (optional default)
  • WAITING_STATUSES (comma-separated)
  • ACTIVE_STATUSES (comma-separated)
  • DONE_STATUSES (comma-separated)

Run examples

Single ticket (good for first validation):

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

For more usage examples, output-path conventions, and metric caveats, see:

  • references/wait-time-estimation.md

Notes

  • Jira status names are workflow-specific; tune waiting/active/done lists per project.
  • Output is designed for downstream analysis (JSON with per-issue diagnostics + summary).
  • This is an estimate from status history; it does not infer effort quality.
  • Prefer a deterministic temp folder shape for ad hoc exports: /tmp/jira-cycle-time-diagnostic/output/... on Unix-like machines, or $env:TEMP/jira-cycle-time-diagnostic/output/... on Windows.
  • The script now creates parent directories for --out automatically.
  • If the right output location is unclear for the machine or team policy, suggest a default and ask the user where the file should live before writing it.

Mini worked example

Quick check math for a real ticket:

  • Example: PIPE-675
  • Cycle start: first In Progress at 2026-06-10T02:07:04.545Z
  • Cycle end: first Done at 2026-06-30T21:44:24.986Z
  • Wait segments in Blocked: 143.780192 h, 71.754138 h, 0.675483 h
  • Wait total: 216.20981333333333 h
  • Cycle total: 499.62234472222224 h
  • Wait %: 216.20981333333333 / 499.62234472222224 = 43.274648%

For the full derivation and caveats, see references/wait-time-estimation.md.

References

  • references/wait-time-estimation.md — script usage examples, metric logic, diagram, and caveats