BottleneckIQ

Documentation

This page covers what BottleneckIQ is, how to install it, and how to read the dashboard. Detailed how-to pages are linked at the bottom.

What it does

BottleneckIQ reads your Jira issue changelogs and computes:

  • Flow metrics — average / P50 / P90 time spent in each workflow status, throughput, WIP averages.
  • Bottleneck detection — identifies the workflow stage most likely slowing your team down right now, scored on three signals (time, WIP, throughput) and explained in one sentence.
  • Trends — current window vs. prior window comparisons surfaced as "improving" / "worsening" / "stable."
  • Charts — WIP Aging (which tickets are stuck right now), Cumulative Flow Diagram (how work is piling up over time), Cycle Time Scatter (which completed tickets took longer than usual).
  • Alerts — rules that fire when a configured threshold is breached.

Everything is computed deterministically from Jira's changelog. The same data always produces the same metrics. AI is used only to translate already-computed signals into one-sentence explanations — it never affects the numbers.

Where the plugin lives in Jira

BottleneckIQ is a jira:projectPage module — it appears in the left-nav of each individual Jira project under "Apps." Click it from a project's nav to see that project's flow analytics. Each project gets its own scoped page.

First-time install

A Jira admin installs the plugin once for the whole site. After install:

  1. Open any project in Jira.
  2. Click "Apps" in the left-nav (or "Apps" → "BottleneckIQ" depending on your nav layout).
  3. The dashboard loads. On a fresh install it shows "Loading flow intelligence…" and then either populated data or an empty state.

Initial backfill

The first time you open BottleneckIQ on a project, the dashboard will be empty — webhooks only capture changes from the install moment forward, so historical issues need a one-time pull. Click Settings → Historical backfill → Start to paginate through every issue your install can read.

While the backfill runs, the Settings tab shows live progress. The dashboard populates as batches complete; you can leave the page open. Hard cap: 50,000 issues per run; sites larger than that should email us for an extension.

After backfill completes, webhooks keep the dashboard fresh going forward.

How sync works

The dashboard is automatically kept in sync via webhooks. When you change a Jira issue's status, assignee, or any tracked field, the dashboard reflects it within ~30 seconds without manual intervention. A daily reconciliation pass catches anything webhooks may have missed.

A "Last sync: 5m ago" indicator at the top of the dashboard shows when the most recent ingest happened. If a change is taking longer than expected to reflect, email support with the issue key and we'll dig into the sync logs.

What you see on the dashboard

The page is organized into tabs:

  • Overview — top-level cards: bottleneck of the week, current vs. prior comparison, alert summary.
  • Flow — average / P50 / P90 time-in-status table, plus the WIP Aging chart and CFD.
  • Cycle Time — scatter of completed issues with cycle-time outliers highlighted.
  • Alerts — list of configured alert rules and their fire history.
  • Settings — historical backfill controls, AI explanation toggle, sprint field configuration, alert rule editor.

Windows and comparisons

Every metric is computed over a configurable window: 7 days, 30 days, 90 days, month-to-date, quarter-to-date, or "current sprint" if your project uses sprints. The Overview cards show current-window vs. prior-window deltas so you can see whether things are improving, worsening, or stable.

Alerts

Alerts fire when a metric crosses a threshold you set:

  • Cycle time alert — fires when P90 cycle time in a status exceeds a threshold.
  • Throughput drop alert — fires when throughput in the current window is more than X% below the prior window.
  • WIP breach alert — fires when active WIP in a status exceeds the configured WIP limit for that status.

Each alert deduplicates: if the same condition is still true the next day, you don't get a second notification. Email delivery is on the roadmap; for now alerts surface in the Alerts tab.

Privacy and security

BottleneckIQ reads only issue metadata, status changelogs, and two custom fields (Story Points and Sprint). It does not read descriptions, comments, attachments, or worklogs. All data lives in AWS US East 1, encrypted at rest. Uninstalling the app deletes your data within minutes.

Full details: Privacy Policy · Security Disclosure · Terms of Service

More documentation

We're expanding this docs site with deep dives on each chart, the window picker, WIP limit configuration, alert templates, and FAQs. If you need something we haven't documented yet, email support@bottleneckiq.com — we typically respond within one business day, and your question often becomes the next docs page.