What should the reviewer check when a builder opens a pull request for docs updates in a monorepo?

In Tares, the reviewer checks each docs pull request against the ticket’s acceptance checks, and the builder merges only after the reviewer’s verdict passes and CI is green. For a monorepo, you also confirm the change stays inside the ticket and that every choice the builder made on its own is flagged in the pull request. The reviewer posts a verdict on every pull request, and a change request sends the builder into another round.

How it works

The software factory for Claude Code runs the same loop for every pull request. A builder works through its tickets one at a time. For each ticket it makes a branch, does the work and opens a pull request. The reviewer reviews that pull request and posts its verdict. Once the verdict passes and CI is green, the builder merges.

The ticket is the reference for the review. Each ticket sits under a milestone, and each milestone carries acceptance checks that the spec session wrote. A docs ticket in a monorepo is judged by the same checks as any other ticket. The full walk-through is in A project, end to end.

What the reviewer should look at on a docs pull request in a monorepo:

• The acceptance checks. Does the diff deliver what the milestone’s checks say, and nothing the ticket did not ask for?
• CI. The merge waits for green CI as well as a passing verdict, so confirm the checks that run on the pull request are the ones the milestone expects.
• Scope. In one project, the reviewer found smaller issues outside the ticket it was reviewing. The orchestrator turned them into a new ticket and placed it in the plan, instead of folding them into the first pull request. Do the same for unrelated edits you spot elsewhere in the repo.
• The pull request description. In the documented project, the builder rewrote an existing description into the documented sections instead of appending to it. Check that the description matches the change.
• Assumptions. When the plan did not cover something, the builder picked a sensible answer, wrote it down as an assumption and flagged it in the pull request. Check that each assumption is stated and that it does not touch existing data or files the ticket left alone.
• The right repo and checkout. The project page’s GitHub fold lists the repos the project changes, where each is checked out and its open and merged pull requests. Use it to confirm the pull request targets the repo the ticket names.

Set it up

1. Write the acceptance checks into the spec. Bring the crew up, then run the spec in the repo and answer Claude Code’s questions. The result is a spec, a plan, an AGENTS.md for the project and milestones with acceptance checks.

tares factory crew up
tares factory spec "what you want to build"

2. Make each docs ticket’s checks concrete. Name the pages or sections the change must touch, so the reviewer has something to compare the diff to.
3. Open the Crew page in the console, at http://127.0.0.1:8787/crew on a local Tares. Pull requests waiting for the reviewer appear in the review queue.
4. Open the project page and unfold Tickets. Each ticket shows the builder that held it, its pull request and its review rounds. Unfold GitHub to check the repo and checkout.
5. Read the pull request against the ticket’s acceptance checks. If something is missing, the reviewer asks for changes and the builder makes them. The next round then reviews the new version.
6. Check Assumptions at the end of the milestone. The orchestrator brings the crew’s own choices to you in one question, and you say whether to keep them. To make an answer stand from now on, say so, for this project or for every project.

If you want to read the plan behind a ticket first, the Docs fold holds the spec, the plan and the project’s AGENTS.md. Get started covers the setup in order.

What you get

• A verdict on every pull request, tied to the ticket’s acceptance checks, with the review rounds recorded next to the ticket.
• Merges that wait for a passing verdict and green CI.
• Out-of-scope findings turned into their own tickets, so the docs pull request stays small and focused.
• Assumptions written down and flagged in the pull request, then brought to you together at the end of the milestone.
• A project page that keeps the whole record: tickets, pull requests, decisions and assumptions.

When something else fits

• If you want to approve every merge yourself, set the crew to wait for your yes before each merge. The documented example of this records most of its decisions as merge approvals.
• If a change needs a human’s judgment on something the plan does not cover, the crew asks you a question in the orchestrator’s session instead of guessing. Answer there, and the answer goes into the Decisions fold.
• If the pull request touches something the acceptance checks never mentioned, ask the reviewer for changes or raise a new ticket instead of widening the current one.

Related