# Reviewing agent work

> What the mission has already proved when a ticket reaches Review, what only you can judge, how to read the evidence, and how to send work back with a note the agent can act on.

This guide helps you review a ticket an agent has finished, quickly and well. By the end you'll know what you can
take as proved, where to spend your attention, and how to send work back so it comes back right the first time.

Reviewing an agent's work isn't like reviewing a teammate's pull request from scratch. By the time a ticket reaches
Review, the mission has already checked a lot of it, and it tells you exactly what it checked and how. Your job is
the part no check can do: deciding whether this is what you wanted.

## Start with what's already proved

Maya from [Intro to By Dawn](https://docs.bydawn.com/learn/intro-to-saw/) opens `BIL-142`, the CSV export, which has just landed in Review. She
reads the **Mission** section first. Its header says how many steps passed, such as **9 of 9 passed**, and each step
shows who did it: **The worker does this**, **SAW does this**, or **You decide**.

Each result also says how it was checked:

- **Verified**: By Dawn ran it and read the exit code. **Tests and build pass** and **Get CI green** are verified, so you
  don't need to run the tests yourself.
- **AI-reviewed**: a model judged the work against a rubric. **Second-opinion review** is one: a separate model reads
  the change and flags problems. It's advice, not proof.
- **Reported**: the worker said so, and nothing checked it. Read these as claims.

**Read the receipts** shows the detail behind each one. A step that failed and was retried says so, so you can see
what the agent had to fix on the way. [How By Dawn shows what was
checked](https://docs.bydawn.com/missions/#how-by-dawn-shows-what-was-checked) explains the three levels.

## Then read the plan

The **Plan** section is what you agreed before the build started. Its **Acceptance checks** are ticked as the agent
met them, so a check left unticked is the first thing to ask about. Next to them, the agent's **confidence** (green,
yellow or red) says how sure it is of the result, and hovering it shows why. A yellow or red badge tells you where to
look first.

## Look at it working

A diff tells you what changed, not whether it works. Before reading code, Maya looks for evidence of the feature
running:

- **Artifacts & previews** holds what the agent attached: a **capture** is a shot or recording of the real thing
  running, and a **mockup**, a **report** or a **doc** may be there too.
- **Browser evidence** is the trail from the agent's own browser, when it tried the app itself.

The capture shows the invoices page with a filter applied and the **Export CSV** button. That answers her biggest
question before she has read a line of code.

## Judge what only you can

Now Maya reads the change in [**Changes**](https://docs.bydawn.com/changes-and-code-view/), which opens the pull request's diff inside By Dawn. She isn't re-checking what
the mission proved. She's checking what it couldn't:

- **Is it what was asked?** The tests prove the code does what the agent meant. Only you know whether that's what
  the customer meant.
- **Is it the right size?** Unasked-for changes, such as a refactor next door or a new dependency, deserve a
  question even when they work.
- **Does it fit?** Names, wording on screen, where things live in the codebase. The conventions your team keeps but
  never wrote down.
- **What happens at the edges?** An empty list, a very long one, a slow network. The acceptance checks cover the
  cases you thought of when you wrote the ticket.

The export's column header says `amount` where the ticket said "total", and nothing tested for that, because only
Maya knew.

## Send it back with a note it can act on

There are three ways to send work back, depending on where you are:

- **On a line.** In **Changes**, [comment on the line](https://docs.bydawn.com/changes-and-code-view/#comment-on-a-line) and choose **Send to agent**. The agent gets your note with the
  lines quoted from its own branch. **Post to #** with the pull request's number puts it on the pull request instead, and **Both** does both.
- **From the ticket.** The box under the agent's feed reads **Send back / follow-up**. A message there resumes the
  agent where it left off, and the card moves back to the Running column.
- **On a checkpoint.** If the mission asks for **Your sign-off**, its card has **Ship it** and **Send back** (see
  [Sign off the work](https://docs.bydawn.com/mission-checkpoints/#sign-off-the-work)).

A comment in the ticket's **Activity** is for people: it doesn't wake the agent. Use one of the three above when you
want the agent to act.

Whichever you use, the note is all the agent has, so make it one it can act on without asking:

> **Vague:** The export isn't right.
>
> **Actionable:** Rename the `amount` column to `total`, as the ticket says. Our finance customers' spreadsheet
> templates look for that header.

Say what to change and why. The reason lets the agent fix the same mistake elsewhere, such as the column name in the
test it wrote. Maya sends her note from the line, and twenty minutes later the ticket is back in Review with the
column renamed and the mission green again.

## When it ships

What happens after you're happy depends on the steps your team ticks. With **Approve the PR** and **Merge the PR**
ticked, By Dawn posts an approving review and merges once CI is green and the branch has no conflicts. With **Your
sign-off** ticked too, By Dawn waits for you to choose **Ship it** first. Without them, you approve and merge the pull
request yourself, the way your team always has. [What By Dawn does with a pull request](https://docs.bydawn.com/pull-requests/#what-by-dawn-does-with-a-pull-request)
has the details. By Dawn never skips your repo's branch protection, and never merges over
a review that asked for changes.

When a mission ends without moving the card on, By Dawn asks **Is this ticket done?** **Done** moves it to Completed, and
**Needs more work** opens the picker for its next mission. [The debrief](https://docs.bydawn.com/mission-checkpoints/#the-debrief) shows what
the finished mission leaves on the ticket.

## Do and don't

**Do:**

- Read the **Mission** section before the code, so you don't check what's already proved.
- Look at a capture of the feature working before you read the diff.
- Give every send-back a reason, in a sentence.

**Don't:**

- Treat an **AI-reviewed** or **Reported** result as proof.
- Send back several small notes one after another. Collect them, and send them together.
- Expect a comment in **Activity** to reach the agent.

## Where to go next

- [Missions and templates](https://docs.bydawn.com/missions/): where a ticket's steps come from, and how a team chooses them.
- [Changes and the code view](https://docs.bydawn.com/changes-and-code-view/): reading a ticket's diff, and every way to comment on a line.
- [Pull requests](https://docs.bydawn.com/pull-requests/): reviewing a pull request in By Dawn, and what By Dawn does with it from draft to merge.
- [Branching and CI](https://docs.bydawn.com/branching-and-ci/): how agents' branches and pull requests fit your repo's workflow.
- [Writing tickets an agent can finish](https://docs.bydawn.com/learn/writing-tickets/): a clearer ticket is a shorter review.

Source: https://docs.bydawn.com/learn/reviewing-agent-work/