# Review

> Confirm that what the graph says is still true in the world. The agent confirms what it checked; the person decides every change.

**Review checks the world, not the record** ([P6](https://flow.ttoss.dev/docs/method/principles.md#p6-the-record-is-an-estimate-review-confirms-reality)). It produces a confirmation that a commitment is still true, or a change to it with its cause. A status is what somebody believed when they wrote it. Review asks whether it still holds: is the PR still open, is Bruno still the one we are waiting on, does this still matter.

## How to do it

### Work through what came up

Five sources feed a review, and each answers a different question:

| Source             | The question                                                                                                                                  | Call                                                                    |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| **Due reviews**    | Which commitments have gone unconfirmed past their date?                                                                                      | [`get-next`](https://flow.ttoss.dev/docs/reference/get-next.md) `slice=review`                   |
| **Waiting on you** | Which decisions and replies does somebody wait for you to give, whoever holds the work?                                                       | [`get-next`](https://flow.ttoss.dev/docs/reference/get-next.md) `slice=waiting_on_me`            |
| **Drift**          | Where does a status contradict what the graph can see, such as a `waiting` task whose wait has cleared, or a `calendar` date that has passed? | [`get-next`](https://flow.ttoss.dev/docs/reference/get-next.md) with a status and a state, below |
| **Flags**          | Which writes went through without the cause or consistency they needed?                                                                       | `needs_reconciliation` on any task                                      |
| **Findings**       | What does the graph contradict about itself, such as a retracted source still used as a cause, or a cycle in what replaces what?              | [`validate-project`](https://flow.ttoss.dev/docs/reference/validate-project.md)                  |

None of these corrects anything on its own. Each one reports, and every change it prompts is a write somebody makes on purpose ([P7](https://flow.ttoss.dev/docs/method/principles.md#p7-report-dont-refuse-reconcile-explicitly)).

### Drift

A task's status is what somebody asserted. Its readiness is what the graph can see holding it, computed from blockers, waits and cycles, and it never reads the status. Drift is where the two part ways, and each case is one [`get-next`](https://flow.ttoss.dev/docs/reference/get-next.md) call, asked by the name of its slice:

| The disagreement                         | Ask `get-next` for   | What it usually means                                                                                                               |
| ---------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Waiting or blocked, and nothing holds it | `slice=hold_cleared` | The reply came or the impediment went. Run the check its wait states, if any; otherwise move it to `active`, or name what holds it. |
| On the calendar, and the date has come   | `slice=date_came`    | It is time. Run the check its wait states, if any; otherwise move it to `active`.                                                   |
| Active, and something still holds it     | `slice=active_held`  | Behind an earlier wave, nothing to do: it frees itself. A stale blocker or a hold that belongs on the status is a change to make.   |

A wait that states a check is a delivery not yet seen in effect ([engage](https://flow.ttoss.dev/docs/method/engage.md#close-with-an-outcome-or-a-reason)): run the check rather than moving it straight back to `active`.

Every [`get-next`](https://flow.ttoss.dev/docs/reference/get-next.md) answer counts these three, the due reviews and what waits on you, so an agent run starts knowing which to ask. Filters given beside a slice narrow it: `slice=hold_cleared&project=proj_…` is the same check for one project.

### Confirm, or change

When a commitment is still true, confirm it with [`confirm-task`](https://flow.ttoss.dev/docs/reference/confirm-task.md). That records that it was checked just now and moves its next review date a week out. Any write that changes the task does the same: whoever moves a task, retargets its wait or attaches what it produced has just looked at it. Priority orders the ready set and sets no review date. An `incubated` idea or `reference` material is not a commitment, so it comes up monthly.

When it is no longer true, change it: move the status, retarget the wait, close it, and record the cause. The change counts as the confirmation, so write only what you checked.

Confirming is a claim that you checked. An agent that confirms says what it looked at. An agent that did not look proposes a confirmation instead of making one.

An agent's confirmation covers the facts it checked: the PR is still open, the wait is still on Bruno. Whether the work still matters is a judgement, and it stays the person's. When the evidence puts it in doubt, the agent proposes a change instead of confirming.

### Flags

A write that needed something it didn't have is accepted and flagged `needs_reconciliation`. Typical causes:

- A move or reprioritisation with no basis.
- A write that landed after someone else's, when `if_unmodified_since` was passed.

The flag stays until [`reconcile-task`](https://flow.ttoss.dev/docs/reference/reconcile-task.md) clears it, and clearing it takes a reason: the cause the original write was missing, written down late but written down. The task's changes keep both, the one that raised the flag and the one that cleared it. A flag never clears on its own and is never cleared without a reason.

A flagged task still shows up in the ready set. The flag is about the record, not about whether the work is real.

## After an absence

When you have been away long enough that you no longer trust the system, the review runs in a fixed order and ends with one action, and it never reads the inbox ([P9](https://flow.ttoss.dev/docs/method/principles.md#p9-recovery-beats-zero)). Each step is [`get-next`](https://flow.ttoss.dev/docs/reference/get-next.md) asked a different way, so this and the ready set can never disagree about what is next:

| Step                          | What it finds                                                                                       | Ask `get-next` for |
| ----------------------------- | --------------------------------------------------------------------------------------------------- | ------------------ |
| 1. Irreversible risks         | Commitments you said matter (they have a priority) whose review is overdue, highest priority first. | `slice=risks`      |
| 2. Near deadlines             | Every date on the calendar, soonest first, with dates already passed ahead of those.                | `slice=deadlines`  |
| 3. Waiting items              | Everything in `waiting`: what others owe you. Some of it has arrived and some of it needs chasing.  | `slice=waiting`    |
| 4. Blockers                   | Everything in `blocked`: what you would have to remove before the work behind it moves.             | `slice=blocked`    |
| 5. The recovering next action | The single top task of the ready set.                                                               | no slice           |

Answer the risk items first, even if only with "still fine, confirm it"; chase what you were waiting on; do the next action, and then you are back in the normal loop. Backlog cleanup — triaging old captures, re-prioritising incubated ideas, tidying the graph — comes after that, if at all. Opening with the inbox finds the biggest number on the screen and the least urgent thing on it, and "let's get everything up to date, then decide" spends the day on the backlog while the risks stay unexamined.

**Example:** [Recover after two weeks away, however full the inbox got](https://flow.ttoss.dev/docs/examples/recover-after-an-absence.md).

## The person

- **Work through what is due, not everything.** Reviewing a task before its date is optional.
- **Kill freely.** Review is where `incubated` things get `discarded` and stale commitments get `cancelled`, and a smaller graph is a more trustworthy one.
- **Watch the size of the ready set.** If it is longer than a week of work, some of it isn't really `active`.

The agent's side is the protocol: [GTF-R1 to GTF-R6](https://flow.ttoss.dev/docs/agents/protocol.md#review).

## Failure modes

- **Confirming without checking.** The review date moves and the record says "checked", but nobody looked. That is worse than leaving it due.
- **Re-reading the record instead of the world.** A review that only reads the task's own fields cannot find out that it is wrong.
- **Treating a change as a confirmation.** An open task you changed but did not confirm is still due.
- **Clearing a flag with a made-up reason.** The flag existed to get the real cause written down. Ask for it.
- **Sweeping everything.** A full weekly sweep does not finish, and the items that really came due get the same attention as the ones that didn't.

## In Flow

| To                                               | Call                                                     |
| ------------------------------------------------ | -------------------------------------------------------- |
| Everything whose review is due                   | [`get-next`](https://flow.ttoss.dev/docs/reference/get-next.md) `slice=review`    |
| Each step after an absence                       | [`get-next`](https://flow.ttoss.dev/docs/reference/get-next.md) with its slice    |
| Record that a commitment is still true           | [`confirm-task`](https://flow.ttoss.dev/docs/reference/confirm-task.md)           |
| Clear a flag, with the reason                    | [`reconcile-task`](https://flow.ttoss.dev/docs/reference/reconcile-task.md)       |
| Find what the graph contradicts about itself     | [`validate-project`](https://flow.ttoss.dev/docs/reference/validate-project.md)   |
| Withdraw a reference that turned out to be wrong | [`retract-reference`](https://flow.ttoss.dev/docs/reference/retract-reference.md) |

**Example:** [Retract evidence and find everything that leaned on it](https://flow.ttoss.dev/docs/examples/retract-evidence-and-find-dependents.md): a source turns out to be wrong, and every commitment that cited it surfaces on its own.