Docs/Concepts/Phase attribution
Phase attribution
Phase attribution is the core idea of Bill-y: every unit of AI coding spend is attributed to a phase of software work. This page defines the taxonomy and the rules that keep it honest. Treat it as the reference for what the words mean everywhere else in the product.
The six phases
| Phase | The work it covers |
|---|---|
understand | Reading and exploring: what does this code do, where is this defined, how does this system behave. |
design | Deciding before building: approaches, tradeoffs, plans, architecture, interface shapes. |
build | Producing the change: writing and editing code, implementing the plan. |
test | Verifying behavior: writing and running tests, reproducing bugs, checking outcomes. |
review | Judging finished work: reviewing diffs, auditing quality, pre-merge scrutiny. |
other | Everything that does not clear the confidence bar, plus genuinely out-of-taxonomy work. |
Every turn of work receives a phase vector across these labels and a dominant phase. The distribution of spend across phases, over a team and a time window, is the product's central object.
Abstains are honest
When the classifier's confidence is below threshold, the turn is labeled other and surfaced as an abstain. Abstains are never silently redistributed across the other five phases.
Note
This rule exists so the numbers stay trustworthy. A phase share that quietly absorbed low-confidence guesses would drift toward plausible-looking noise. An abstain rate you can see is information; a hidden one is contamination. The console warns when the abstain share of a window is high enough to matter.
Two bases: tokens and queries
Every phase share can be computed on two bases, and the basis is always stated:
- By tokens: where the volume (and therefore the money) went. Long generation-heavy work dominates.
- By queries: what people asked for most, with every turn counting equally. Interaction patterns dominate.
The two views disagree in useful ways. A team can be query-heavy in understand while being token-heavy in build; that is a normal, healthy shape. A share quoted without its basis is not a Bill-y number.
What phase attribution is not
- It is not a productivity score. Phases describe the shape of work, not its quality.
- It is not a per-developer verdict. The analytics plane operates at team level, with person-level views gated separately and suppressed for small groups.
- It is not a target. The moment a phase share becomes a quota, it stops measuring anything. Bill-y's governance design assumes distributions are read, discussed and investigated, never assigned.
Why phases and not totals
Raw totals answer "how much". Phases answer "on what". Two teams with identical monthly spend can have completely different shapes: one spends mostly in build with visible design and test phases, the other burns everything in blind generation with no visible verification. The totals are identical; the stories are not. Phase attribution is the difference between metering AI and managing it.