# Build, review, and land one change

The most reliable agent workflow is a small loop: define one change, implement it, review the exact result, fix anything real, run the project gate, and land only that slice. Solo keeps the writer, reviewer, commands, and handoff in one project while the lead agent stays responsible for the final decision.

This works well for a bug fix, a small feature, a migration, or any other change that can be reviewed and verified on its own.

## Start with the landing contract

Before anyone edits, tell the lead agent what counts as one finished slice. Include the intended behavior, the allowed area of the repository, the verification you expect, and anything it must leave alone.

You can start with a prompt like this:

```text
Use Solo to take this change from implementation through review.

First define one landing-sized slice: intended behavior, owned files, non-goals,
tests, and stop conditions. Use one writer. When focused checks pass, spawn one
independent read-only reviewer for the exact diff. Validate its findings against
the code, send accepted fixes back to the writer, run the repository's normal
quality gate, and show me the final result. Preserve unrelated worktree changes.
Do not commit or push unless I ask.
```

The important part is the boundary. “Improve billing” is not a slice. “Make retrying a failed invoice idempotent, with a regression test for duplicate webhook delivery” is.

For a longer change, ask the lead to put the contract in a [scratchpad and todo](./scratchpads-and-todos.md). For a short change, the prompt itself may be enough.

## Keep one writer

Give implementation ownership to one agent at a time. The lead can keep the edit or [spawn a worker](./agents-spawning-agents.md), but there should be one clear writer for the slice.

Ask the writer to:

- Inspect the relevant behavior before editing.
- Add or identify a test that would fail for the bug or missing behavior.
- Make the smallest change that satisfies the contract.
- Run focused checks before broader project checks.
- Report changed files, test results, assumptions, and remaining risk.

Parallel research is fine when it does not overlap with the writer. For example, one read-only agent can trace an unfamiliar API while the writer prepares a regression test. Two agents editing the same files usually create more integration work than they save.

## Review the result, not the idea

Once the focused checks pass, give an independent reviewer a frozen target: a commit, commit range, or the exact uncommitted diff and file list. Give it the intended behavior and existing test evidence, but do not ask it to continue implementation.

A useful review brief is:

```text
Review this exact change read-only. Check correctness, regressions, data safety,
and missing behavior-level tests. Lead with findings ordered by severity and cite
the relevant files. Distinguish demonstrated defects from preferences. Do not
edit files, broaden the task, or spawn more agents. Return "no material findings"
when that is the honest result.
```

One reviewer is enough for most bounded changes. Use a [review panel](./independent-review-panel.md) only when different technical lenses will materially improve the decision.

Ask the lead to set one [idle wake-up timer](../mcp-tools/timers.md) for the reviewer instead of repeatedly checking it. When the reviewer goes idle, the lead should inspect its actual output, capture the useful result, and close the reviewer when no follow-up is needed.

## Validate findings before fixing them

The lead owns the review verdict. It should trace every blocking claim through the current code and reject findings that depend on a stale diff, an incorrect assumption, or personal taste.

For an accepted finding:

1. State the concrete behavior that is wrong or insufficiently covered.
2. Send the smallest correction back to the existing writer.
3. Run the focused regression check again.
4. Ask the same reviewer for a second pass only when its original concern needs confirmation.

Do not create a new reviewer for every correction. A review loop should converge, not grow a family tree.

## Run the real project gate

After focused checks are green, run the repository's normal quality command. This is usually a checked-in test, lint, format, build, or pre-push command rather than a custom validation script invented for the session.

Have the lead classify failures before changing anything:

- A failure caused by the slice should be fixed inside the slice.
- An unrelated existing failure should be reported and preserved.
- An environment or validation failure should not be presented as a product defect.
- A failure that requires a much broader change should stop the landing and become a separate todo.

Finally, ask the lead to inspect git status and the final diff. It should stage and commit only the intended files when authorized, and it should never push merely because the local gate passed.

## Close the loop

Before closing agents, preserve any follow-up that should survive the session. Put durable context in the scratchpad and concrete work in todos or todo comments. Then [close finished reviewers and workers](../agents/closing-agents.md) whose handoffs have been captured.

A finished loop should leave you with:

- One understandable change.
- Evidence for the behavior it adds or fixes.
- An independent review tied to the exact result.
- A passing project gate, or a clearly explained external failure.
- A clean boundary between the landed slice and remaining work.

If you use this loop often, save the opening prompt as a [global prompt template](../prompt-templates/overview.md). Add placeholders for the goal, owned files, and quality command so the workflow stays consistent without turning every change into the same implementation plan.

---

Are you a human? Read this doc on the web: https://soloterm.com/docs/workflows/build-review-land