> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fermata.run/llms.txt
> Use this file to discover all available pages before exploring further.
# Review and the pull request
> Read the diff the agents produced and the work review's verdict, run an optional code review, ask for changes, then open the pull request or land the work locally. You merge.
Sooner or later the agents stop and it is your turn. The piece has reached its Review phase and the changes are sitting on its branch waiting on a human. This page covers how to read the diff, how to send work back, and how the change lands. If you got here from the [first piece walkthrough](/start/first-piece), this is the step you were promised.
## The diff
Review opens on the whole branch diff, headed by the file count and the total insertions and deletions. A file tree on the left lists every file the agents touched with its insertions and deletions. Click a file to open its diff on the right.
Deep folder chains flatten. Instead of five nested rows for a single path, Fermata collapses the chain into one entry, so `src/features/auth/components/LoginForm.tsx` is one row rather than five.
Two things the panel tells you that are easy to miss. It shows committed work only, and says so when the worktree has uncommitted changes that are not in the diff. And after a round of changes it can show the round delta on its own, so you can read what moved since you last looked instead of re-reading the whole branch.
## The work review
Before Review opens, one more agent runs after the last agent in the graph: the work review. It checks that the plan was followed and the work was done. It reads the spec, the strategy, each agent's handoff, and the branch diff, judges every acceptance criterion in the spec from that evidence, and writes a verdict. It never edits a file, never commits, and never runs the build or the tests; projects validate in their own way, and what the review looks for is a completion claim with no work behind it.
The verdict is the **Work Review** artifact in the Review surface, next to the diff. Its header names how long the review took, not what it cost; the review's own spend stays in its record and in the piece's usage total, not on this card. A failing verdict is a stop: on the Auto and Loop lanes the piece parks at Review even with the review gate off, and you decide.
**Send Back to Agents…** opens a dialog titled "Send Back to Agents?". It lists one option per failed agent, quoted with the review's own word for what it found ("Send Task 5 Back (Not committed)", "Send Task 5 Back (Unclear)"), plus a combined option when more than one agent failed ("Send Tasks 1 and 5 Back"). Pick one and those agents run again, with the review running again after them; anything already finished, the branch, and the worktree are left untouched. The agent's next brief opens with a "Why This Task Is Running Again" section, so the agent starts from what the review found instead of from a blank slate. Or leave the dialog and approve the review to move on.
It is on by default. **Run work review after agents**, in the Flow Configuration sheet, turns it off per piece, and the same row in Settings → Loop sets the default. See [gates](/control/gates).
## Run Code Review
Code review is experimental. It can be slow, miss problems, or fail partway through a run, and it may change between releases. It is also token-heavy: a review reads the whole diff and the code around it, so a single run can cost as much as one of the agents that wrote the change, and Max costs more than High. Treat its findings as advice, not a gate: the pull request never waits on it.
**Run Code Review** is an Edge feature: it appears once Edge and its **Code review** switch are on in Settings → Edge. It is a pass over the diff that comes back with findings you can act on, send back to an agent to fix, or ignore.
Its header carries three controls for the run about to happen:
| Control | What it sets |
| - | - |
| **Depth** | High is fast and high-confidence; Max casts a wider net and also surfaces lower-confidence findings to triage. |
| Model chip | The model this run uses. |
| Effort menu | A fixed set of levels, plus Auto, which omits the flag and lets the CLI decide. |
All three apply to this run only, not to the piece's own review settings. They stay open to change before a run starts or right after **Re-run** is clicked; once a run is in flight, or a result is sitting on screen, they freeze, so the findings shown and the settings that produced them can never disagree.
It is advisory: it never blocks the pull request and does not replace your read of the code.
You can also have it run by itself before the pull request opens on a hands-off run. That is the **Run code review before PR** switch, covered on [gates](/control/gates).
## Request Changes
If the work needs adjustment, click **Request Changes** and type a short follow-up. Fermata starts an interactive session on the piece's own branch and worktree, so the fix lands on the same branch as everything else. The agent is told not to commit: when the turn ends a commit card appears with the changed-file count and an editable message, and you pick **Commit**, **Commit & Push**, or **Discard**.
This is a round, not a restart. You can do it as many times as the work needs, and the diff picks the new commits up. The backward edges that actually discard a phase are **Rework Spec** and **Rework Strategy**, which only exist before agents start; see [Strategy](/piece/strategy).
**Reopen Agents** is the other way back, offered on the Review phase itself and, once the piece has settled at Done, from its **⋯** menu as **Reopen Unfinished Agents…**. Either one asks first: the confirmation, titled "Reopen Unfinished Agents?", names how many agents never finished, states what it found about the PR (open and ready to pick up new commits, or already merged or closed onto a branch that no longer matters), and confirms the piece returns to the Agents phase, paused, with completed agents, the branch, and the worktree left untouched.
## How the work lands
Three ways out, depending on what the work needs.
| Control | What happens |
| - | - |
| **Create PR** | Fermata pushes the branch and opens a pull request through `gh`. Once one is open, the button becomes **Push to PR** and later commits just push to it. |
| **Merge Back** | Merges the piece's branch into your base branch locally, no pull request involved. It offers to stash first if the base branch is dirty. |
| **Mark as Done** | Closes the piece out without opening anything, then asks what to do with the worktree. |
**Merge Back** suits work that never needed a review round: a chore, a version bump, something you already read line by line. It is plain git, so it is also the ending to use on a remote that is not GitHub. **Mark as Done** is for work that landed some other way, or that you decided against.
One switch picks between those endings before a hands-off run gets here. **Create pull request**, in the Flow Configuration sheet and on by default, ends a hands-off run with a pull request. Turn it off and the run completes locally without one, branch kept and worktree removed. It is not a gate. See [gates](/control/gates).
Fermata opens the pull request. It never merges on its own. You merge, from the piece's Done view or on GitHub.
## Resolving a conflict
A pull request can fall out of sync with its base branch while it waits on you: someone else merges first, and the branch no longer applies cleanly. Fermata surfaces this in place of the merge control on the Done view rather than as a separate alert.
**Solve Conflicts** starts an assisted session that brings the base branch in and works through the conflicts; Fermata pushes the branch once the tree is clean. Step away before it finishes and the same control becomes **Resume Resolution**, re-entering the merge or rebase left in progress in the worktree. While a resolution session is running, it becomes **Open Solving Conflict Session** instead, so you can watch it or answer it; all three sit behind an amber "Resolving" loader while the session is actually doing the work.
Each of the three ways it can end tells you by name: resolved and pushed, resolved but the push failed, or stopped with conflicts still open. See [notifications](/control/notifications#when-conflict-resolution-finishes) for the exact wording of each.
## What happens to the worktree
The worktree stays put while the pull request is open, because that is when the branch gets the most work: another round of changes, addressing review comments, a code-review fix, a conflict resolution, all of it runs there.
Once the pull request merges, Fermata removes the worktree directory on its own and keeps the branch. Three things stop it: an uncommitted tree, a piece you already marked done, and a session still working in that worktree.
**Mark as Done** asks instead of deciding. The dialog names the branch and offers **Done & Delete Worktree + Branch**, **Done & Keep Branch Only**, and **Done & Keep Everything**. Turning on **Automatically tear down the worktree when marked Done** in Settings → Loop skips the question: the worktree goes, and the branch goes with it once a pull request exists. With no pull request the branch is always kept, so un-pushed work is never lost.
A standalone session follows a different rule: stop one with a clean tree and no commits and its worktree and branch are cleaned up for you. See [the Canvas and standalone sessions](/surfaces/canvas-and-sessions).
## What the run leaves behind
When a piece completes, Fermata writes two documents from the run's full context and saves them with the piece, beside its spec: `summary.md`, what was built, and `learnings.md`, what the run found out about your codebase along the way.
The Done view's **Summary** section is always there, in whichever of three states applies: the text itself once it lands, "Writing the summary from the spec, strategy, and agent handoffs…" while it generates, or "The summary didn't generate." next to a **Retry** button, covering a failed run, an empty run, and a piece marked done before a summary ever ran. The section keeps the same shape across all three, so the screen does not jump when the summary arrives.
Both `summary.md` and `learnings.md` surface on the piece's Done view under **Artifacts**, as chips alongside the spec, the strategy, the work review's verdict, the code review findings when Edge ran one, and a link to the pull request. They are plain markdown on your disk, so the next piece in that repo, and you in three months, can read them.
They live in a `.fermata/` folder at the root of the project, along with the piece's spec, strategy, and analysis. Fermata adds `.fermata/` to your `.gitignore` the first time it writes there, so none of it lands in the diff or the pull request. Commit it deliberately if you want the paper trail shared.
A hand edit to `spec.md` or `strategy.md` on disk, made while the piece is still open, is kept: the next save adopts what changed on disk into memory instead of overwriting it. If both sides changed since the last save, Fermata's own memory wins the file, but the edit found on disk is not discarded: it is kept once, alongside it, as `spec.conflict-.md` or `strategy.conflict-.md`, so an edit made outside the app is never silently lost, even when it loses the race.
## The diff
Review opens on the whole branch diff, headed by the file count and the total insertions and deletions. A file tree on the left lists every file the agents touched with its insertions and deletions. Click a file to open its diff on the right.
Deep folder chains flatten. Instead of five nested rows for a single path, Fermata collapses the chain into one entry, so `src/features/auth/components/LoginForm.tsx` is one row rather than five.
Two things the panel tells you that are easy to miss. It shows committed work only, and says so when the worktree has uncommitted changes that are not in the diff. And after a round of changes it can show the round delta on its own, so you can read what moved since you last looked instead of re-reading the whole branch.
## The work review
Before Review opens, one more agent runs after the last agent in the graph: the work review. It checks that the plan was followed and the work was done. It reads the spec, the strategy, each agent's handoff, and the branch diff, judges every acceptance criterion in the spec from that evidence, and writes a verdict. It never edits a file, never commits, and never runs the build or the tests; projects validate in their own way, and what the review looks for is a completion claim with no work behind it.
The verdict is the **Work Review** artifact in the Review surface, next to the diff. Its header names how long the review took, not what it cost; the review's own spend stays in its record and in the piece's usage total, not on this card. A failing verdict is a stop: on the Auto and Loop lanes the piece parks at Review even with the review gate off, and you decide.
**Send Back to Agents…** opens a dialog titled "Send Back to Agents?". It lists one option per failed agent, quoted with the review's own word for what it found ("Send Task 5 Back (Not committed)", "Send Task 5 Back (Unclear)"), plus a combined option when more than one agent failed ("Send Tasks 1 and 5 Back"). Pick one and those agents run again, with the review running again after them; anything already finished, the branch, and the worktree are left untouched. The agent's next brief opens with a "Why This Task Is Running Again" section, so the agent starts from what the review found instead of from a blank slate. Or leave the dialog and approve the review to move on.
It is on by default. **Run work review after agents**, in the Flow Configuration sheet, turns it off per piece, and the same row in Settings → Loop sets the default. See [gates](/control/gates).
## Run Code Review
It is advisory: it never blocks the pull request and does not replace your read of the code.
You can also have it run by itself before the pull request opens on a hands-off run. That is the **Run code review before PR** switch, covered on [gates](/control/gates).
## Request Changes
If the work needs adjustment, click **Request Changes** and type a short follow-up. Fermata starts an interactive session on the piece's own branch and worktree, so the fix lands on the same branch as everything else. The agent is told not to commit: when the turn ends a commit card appears with the changed-file count and an editable message, and you pick **Commit**, **Commit & Push**, or **Discard**.
This is a round, not a restart. You can do it as many times as the work needs, and the diff picks the new commits up. The backward edges that actually discard a phase are **Rework Spec** and **Rework Strategy**, which only exist before agents start; see [Strategy](/piece/strategy).
**Reopen Agents** is the other way back, offered on the Review phase itself and, once the piece has settled at Done, from its **⋯** menu as **Reopen Unfinished Agents…**. Either one asks first: the confirmation, titled "Reopen Unfinished Agents?", names how many agents never finished, states what it found about the PR (open and ready to pick up new commits, or already merged or closed onto a branch that no longer matters), and confirms the piece returns to the Agents phase, paused, with completed agents, the branch, and the worktree left untouched.
## How the work lands
Three ways out, depending on what the work needs.
| Control | What happens |
| - | - |
| **Create PR** | Fermata pushes the branch and opens a pull request through `gh`. Once one is open, the button becomes **Push to PR** and later commits just push to it. |
| **Merge Back** | Merges the piece's branch into your base branch locally, no pull request involved. It offers to stash first if the base branch is dirty. |
| **Mark as Done** | Closes the piece out without opening anything, then asks what to do with the worktree. |
**Merge Back** suits work that never needed a review round: a chore, a version bump, something you already read line by line. It is plain git, so it is also the ending to use on a remote that is not GitHub. **Mark as Done** is for work that landed some other way, or that you decided against.
One switch picks between those endings before a hands-off run gets here. **Create pull request**, in the Flow Configuration sheet and on by default, ends a hands-off run with a pull request. Turn it off and the run completes locally without one, branch kept and worktree removed. It is not a gate. See [gates](/control/gates).
Fermata opens the pull request. It never merges on its own. You merge, from the piece's Done view or on GitHub.
## Resolving a conflict
A pull request can fall out of sync with its base branch while it waits on you: someone else merges first, and the branch no longer applies cleanly. Fermata surfaces this in place of the merge control on the Done view rather than as a separate alert.
**Solve Conflicts** starts an assisted session that brings the base branch in and works through the conflicts; Fermata pushes the branch once the tree is clean. Step away before it finishes and the same control becomes **Resume Resolution**, re-entering the merge or rebase left in progress in the worktree. While a resolution session is running, it becomes **Open Solving Conflict Session** instead, so you can watch it or answer it; all three sit behind an amber "Resolving" loader while the session is actually doing the work.
Each of the three ways it can end tells you by name: resolved and pushed, resolved but the push failed, or stopped with conflicts still open. See [notifications](/control/notifications#when-conflict-resolution-finishes) for the exact wording of each.
## What happens to the worktree
The worktree stays put while the pull request is open, because that is when the branch gets the most work: another round of changes, addressing review comments, a code-review fix, a conflict resolution, all of it runs there.
Once the pull request merges, Fermata removes the worktree directory on its own and keeps the branch. Three things stop it: an uncommitted tree, a piece you already marked done, and a session still working in that worktree.
**Mark as Done** asks instead of deciding. The dialog names the branch and offers **Done & Delete Worktree + Branch**, **Done & Keep Branch Only**, and **Done & Keep Everything**. Turning on **Automatically tear down the worktree when marked Done** in Settings → Loop skips the question: the worktree goes, and the branch goes with it once a pull request exists. With no pull request the branch is always kept, so un-pushed work is never lost.
A standalone session follows a different rule: stop one with a clean tree and no commits and its worktree and branch are cleaned up for you. See [the Canvas and standalone sessions](/surfaces/canvas-and-sessions).
## What the run leaves behind
When a piece completes, Fermata writes two documents from the run's full context and saves them with the piece, beside its spec: `summary.md`, what was built, and `learnings.md`, what the run found out about your codebase along the way.
The Done view's **Summary** section is always there, in whichever of three states applies: the text itself once it lands, "Writing the summary from the spec, strategy, and agent handoffs…" while it generates, or "The summary didn't generate." next to a **Retry** button, covering a failed run, an empty run, and a piece marked done before a summary ever ran. The section keeps the same shape across all three, so the screen does not jump when the summary arrives.
Both `summary.md` and `learnings.md` surface on the piece's Done view under **Artifacts**, as chips alongside the spec, the strategy, the work review's verdict, the code review findings when Edge ran one, and a link to the pull request. They are plain markdown on your disk, so the next piece in that repo, and you in three months, can read them.
They live in a `.fermata/` folder at the root of the project, along with the piece's spec, strategy, and analysis. Fermata adds `.fermata/` to your `.gitignore` the first time it writes there, so none of it lands in the diff or the pull request. Commit it deliberately if you want the paper trail shared.
A hand edit to `spec.md` or `strategy.md` on disk, made while the piece is still open, is kept: the next save adopts what changed on disk into memory instead of overwriting it. If both sides changed since the last save, Fermata's own memory wins the file, but the edit found on disk is not discarded: it is kept once, alongside it, as `spec.conflict-