# 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`](https://flow.ttoss.dev/docs/reference/get-project-metrics.md)                    |
| The same, over one tag (`bug`, for instance) | [`get-project-metrics`](https://flow.ttoss.dev/docs/reference/get-project-metrics.md) with `tag`         |
| The person queue, per person                 | [`get-project-metrics`](https://flow.ttoss.dev/docs/reference/get-project-metrics.md) with `group_by=on` |
| What agent runs spent, by what became of it  | [`list-agent-runs`](https://flow.ttoss.dev/docs/reference/list-agent-runs.md) with `group_by=outcome`    |
| The inbox                                    | [`list-captures`](https://flow.ttoss.dev/docs/reference/list-captures.md)                                |

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).
- `entered` and `left`: 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](https://flow.ttoss.dev/docs/practice/sessions.md#once-a-week) is for.

## Spend

[`list-agent-runs`](https://flow.ttoss.dev/docs/reference/list-agent-runs.md) 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`](https://flow.ttoss.dev/docs/reference/list-captures.md) 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](https://flow.ttoss.dev/docs/practice/sessions.md#ending-a-session) before stopping.
