Practice
Reading a project's health
Whether a project's queues are filling or draining. What each measure counts, how to read it, and what it does not tell you.
The graph says what holds each task now. The health measures say how work has been moving: which queues are growing, how long work sits in each one, how much comes back, and what the agents spent. Everything is computed from the history Flow already keeps for each task, meaning its status moves, its waits and the blocks edges into it. Nothing is stored apart from that history, and nothing has to be reported by hand. So any past window can be read again later, with the same answer.
Three operations answer the measures:
| Measure | Operation |
|---|---|
| Queues, delivery, rework, incubated work | get-project-metrics |
The same, over one tag (bug, for instance) |
get-project-metrics with tag |
| The person queue, per person | get-project-metrics with group_by=on |
| What agent runs spent, by what became of it | list-agent-runs with group_by=outcome |
| The inbox | list-captures |
In the console, a project’s page links to its health view, at /app/projects/{id}/health. The view draws the seven groups below for the window you pick (7, 14 or 30 days) beside the window of the same length before it. The window is part of the address, so a link to one week stays a link to that week. Earlier and Later move the window back and forward. From an agent, ask for the same thing in words: “How is this project flowing?” or “Compare this week with the last.”
Only work counts: tasks of kind commitment, goal and decision. Notes, claims and evidence have no queue to sit in.
A row is a state
Each row of get-project-metrics is one state a task can be in: its status, its readiness state, and on, which is true when somebody’s answer holds it. That is an external wait on a person or a team, or an open decision that blocks it. For each row:
open: how many tasks are in that state at the end of the window.open_days: how long those have been in it, as the median (p50) and the 90th percentile (p90).enteredandleft: how many times a task came into the state, or went out of it, during the window.left_days: how long each of the tasks that left had stayed.
A spread is null when nothing was measured, for instance left_days for a state nothing left. That means “no data”, not zero.
Reading the queues
Filling or draining. Compare entered with left. More in than out means the queue grew, fewer means it shrank, and equal means it held. One window is noise. The same direction two windows running is a trend, which is why the console always shows the window before.
What is stuck. open says how much is in a queue, and the p90 of open_days says how long its oldest work has waited. A short queue with a long p90 holds one task that everybody is walking past. Open that state in the graph and find it.
How long a pass takes. The p50 of left_days is how long a task usually stays in a state before it moves on. If that number rises while open stays flat, the queue is not bigger, it is just slower.
The person queue first. Rows with on true are work that only somebody’s answer can free: a review, a decision, a reply. Waiting there costs the most, because nothing else in the graph can move it, and it is the one queue a team controls directly by answering. The console puts these rows first. When the person queue grows two windows running, decisions are the bottleneck, and adding agents or tasks will not help.
Whose answer it waits on. Ask with group_by=on and the answer adds groups: the same rows again for each member or team whose answer holds the work, then one for external waits on nobody. A decision that blocks work counts under whoever the decision waits on. When several answers hold one task, it counts under the first holder by id, so no task is counted twice. A handoff from one person to another is a move out of the first person’s row and into the next. Read each person’s entered against left the way you read the whole queue’s: one growing two windows running is the person to talk to.
Delivery
completed counts the tasks completed in the window, and days is their lead time, from creation to completion. Read the p90 beside the p50: a p50 that holds while the p90 climbs means most work flows and a few tasks drag on.
Rework
moves counts each pass from one state to another during the window. A pass whose end is a bare status (no state) is a task that closed. Rework is the passes back to active from a waiting task held by something other than a person’s answer (a gate, such as CI or a deploy), or from calendar. Each one is work that was handed on and came back. A few are normal, since a review that never sends anything back is not reviewing. A count that climbs means work is leaving before it is ready.
Failure demand
Ask for the same measures with tag: [bug], or whatever tag the project uses for defects. These rows are work that exists only because earlier work failed. When their entered grows faster than the project’s, new work is mostly repair.
Incubated work
The passes out of incubated say what became of the ideas somebody wrote down instead of doing: promoted into open work, or discarded. Discarding is healthy, since capturing an idea was never a promise to do it. What to look for is an incubated queue whose entered keeps outrunning left: ideas are being written down and never looked at again. That is what the weekly review is for.
Spend
list-agent-runs with group_by=outcome groups the runs started in the window by what became of the tasks they worked on: completed, still open, or dropped, meaning closed without completing. dropped is spend with nothing to show. It is worth reading on its own, though some of it is the cost of finding out a task was not worth doing. A run that worked on tasks with different outcomes is counted in each group, so the groups do not add up to the total. unpriced counts runs that reported no cost yet, so a total with any unpriced runs is a lower bound.
The inbox
list-captures answers total, every capture nobody has triaged yet, and the oldest one’s inbox_age_ms. The inbox belongs to you and not to a project, because a capture is in no project until it is triaged. So this number is the same on every project’s health view.
What the measures are not
No number is a target. The console draws no goal, no threshold and no red or green. A team that aims at a number gets the number: close fast and throughput rises, while the work reopens as rework somewhere else. The measures are for finding where work waits, not for grading anyone.
No number is derived from another. Flow answers counts and spreads. It does not divide them into ratios such as “weeks to clear the queue”, “share of rework” or “cost per delivery”, and the console does not compute them either. A ratio hides which of its two numbers moved, and both numbers are already on screen.
Readiness is recomputed, not remembered. A task’s past state is worked out again from its history, with today’s rules. If a past wait or edge was never written down, the history cannot show it, and the time lands in whatever state the task appeared to be in. The measures are only as honest as the graph they read, which is one more reason to write back before stopping.