bottleneck-detector

bottleneck-detector

The science

• Theory of constraints (Goldratt) — system throughput = throughput of the slowest stage. Optimizing non-bottleneck stages adds zero throughput.
• Little's Law (queueing theory) — WIP = throughput × cycle_time. A stage with high WIP × high cycle time is the bottleneck.
• Leverage ordering (econ) — action recommendations should be ranked by expected throughput improvement, not by ease.

Input

{
  "snapshot_date": "2026-05-12",
  "stages": [
    {
      "name": "Todo",
      "current_wip": 5,
      "limit": null,
      "items": [{"key": "TEAM-103", "age_days": 14, "title": "..."}]
    },
    {
      "name": "In Progress",
      "current_wip": 0,
      "limit": 1,
      "items": []
    },
    {
      "name": "In Review",
      "current_wip": 3,
      "limit": 2,
      "items": [
        {"key": "TEAM-101", "age_days": 8, "title": "...", "last_activity": "2026-05-07"},
        {"key": "TEAM-102", "age_days": 4, "title": "...", "last_activity": "2026-05-11"}
      ]
    }
  ],
  "cycle_time_stats": {
    "7d_median_days": 2.3,
    "30d_median_days": 1.8,
    "trend": "increasing"
  },
  "critical_path_map": {
    "TEAM-101": {"on_critical_path": true,  "path_length_pt": 11.0},
    "TEAM-102": {"on_critical_path": false, "path_length_pt":  3.0},
    "TEAM-103": {"on_critical_path": false, "path_length_pt":  1.0}
  }
}

The critical_path_map field is optional. When absent, fall back to the leverage rules below as-is. When present, it maps issue_id to {on_critical_path: bool, path_length_pt: float} computed by critical_path.py.

Output

{
  "bottleneck_stage": "In Review",
  "diagnosis": "PRs are landing slower than they're opening. In Review WIP (3) exceeds limit (2); oldest item TEAM-101 has 8 days of age and no comment activity in 5 days, indicating reviewer-side block. 7-day cycle-time median (2.3d) is 28% higher than 30-day baseline (1.8d), consistent with the In Review backlog growing.",
  "recommended_actions": [
    {
      "action": "Land TEAM-101 today before opening any new PR",
      "leverage": "high",
      "estimated_throughput_gain": "+1 PR/day for this week if blockage clears"
    },
    {
      "action": "Switch TEAM-102 from draft to ready (no work, just state)",
      "leverage": "medium",
      "estimated_throughput_gain": "removes 1 item from invisible queue"
    },
    {
      "action": "Decide on TEAM-103 (Todo, 14d) — close or revive",
      "leverage": "low",
      "estimated_throughput_gain": "frees mental WIP, not real WIP"
    }
  ],
  "confidence": "high"
}

Decision rules

1. Stage selection: bottleneck = argmax(stage.current_wip × stage.mean_age) where mean_age falls back to a constant if not provided.
2. Diagnosis:
   • State the stage and the metrics that name it
   • Identify the WHY (reviewer-block, no In Progress capacity, etc.)
   • Cite the cycle-time trend if it corroborates
3. Actions:
   • 1-3 actions
   • First action is highest-leverage (specific item to move, not generic advice)
   • Each action has an leverage label and a brief impact statement
4. Confidence:
   • high if WIP > limit AND cycle-time trending up
   • medium if WIP at limit but trend flat
   • low if metrics are sparse (e.g. < 5 items in flight total)

Critical-path integration

When critical_path_map is present, weight each recommended action by whether the item it touches sits on the critical path:

• A CP item moving forward earns one leverage tier higher than the same action on a non-CP item would (medium -> high, low -> medium). Reason: only the bottleneck stage on the critical path improves end-to-end throughput (Goldratt, The Goal, 1984).
• A non-CP item never beats a CP item at the same leverage tier. If two candidate actions tie on the WIP/age signal, prefer the CP one.
• In the action's estimated_throughput_gain string, mention CP status when relevant (e.g. "TEAM-101 sits on CP, length 11pt").
• Never recommend stalling a CP item to make room for a non-CP item.
• If the map is empty {} or missing, behave exactly as before — do not invent CP status, and do not penalize items for unknown status.

What you do NOT do

• Suggest closing items without evidence they're abandoned
• Recommend hiring / org changes (out of scope)
• Generic productivity advice (the user has the data; ground every recommendation in this snapshot's data)
• Use vague terms like "consider" — actions are concrete and named
• Emit emoji or markdown formatting in the JSON

Failure modes

Symptom	Cause	Action
Empty stages	No items in flight	bottleneck_stage: null, diagnosis: "Nothing in flight. Pull new work freely."
All stages within limit + cycle time flat	Healthy system	bottleneck_stage: null, diagnosis: "No bottleneck detected."
Conflicting signals (high WIP but cycle time short)	Recent burst	confidence: low, note: "Possibly a one-day spike — re-check tomorrow"