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

Tares shows you each docs pull request with its ticket, its review rounds and the reviewer’s verdict, so you check it against the milestone’s acceptance checks. The reviewer reviews every pull request and posts a verdict. You decide what the bar is for a docs site by writing it into the spec.

How it works

Every project starts with a spec session. That session produces a spec, a plan, an AGENTS.md for the project and milestones, and each milestone carries acceptance checks. The builder works through the tickets one at a time. For each ticket it makes a branch, does the work and opens a pull request.

The reviewer then reviews that pull request and posts its verdict. Pull requests waiting for the reviewer appear in a review queue on the Crew page (http://127.0.0.1:8787/crew locally).

What happens after the verdict depends on what you chose at crew up:

• When the reviewer passes the pull request and CI is green, the builder merges. In one project the crew merged on its own at that point.
• If the reviewer asks for changes, the builder makes them and a next round follows. In the example project, two tickets took a second round and then passed.
• In another project the crew waited for the person’s yes before every merge. Each approval sits in the Decisions fold, as you typed it.

The reviewer can also find smaller issues outside the ticket it is reviewing. The orchestrator turns them into a new ticket and places it in the plan, so they get fixed instead of lost.

When the crew meets something the plan does not cover, it picks a sensible answer, writes it down as an assumption and carries on. In the example project the builder flagged one such choice in its pull request, and the project page lists every assumption.

Set it up

Put the docs-site bar in the places the crew reads. The starting prompt, the spec, the plan and the project’s AGENTS.md are what every session that builds the project reads, and you can edit them from the project’s All docs list.

1. Start the spec session in the docs repo and name the docs change you want. Follow Get started for the full setup first if the crew is not running yet.

tares factory spec "what you want to build"

2. Write acceptance checks for the milestone that fit a docs change. For example: the pages the ticket names are the pages that changed, the docs build passes in CI, and links and code samples on the changed pages still work. Use your own repo’s conventions and write the ones that matter to you.
3. Put the repo’s docs conventions, such as where pages live and how they are named, in the project’s AGENTS.md.
4. Choose at crew up how far the crew may go. The Crew page shows that choice under How far the crew may go.
5. When a docs pull request arrives, open its ticket in the Tickets fold. Read the pull request, the review rounds and the verdict beside the milestone’s acceptance checks.
6. Read the pull request description. In the example project the builder rewrote an existing description into the documented sections, and a pull request that states what it changed is easier to judge.
7. Look at the Assumptions fold for any choice the builder made that the ticket did not cover, such as a file it used instead of the one the working doc named, and say whether you keep it.

The A project, end to end page walks through these folds on a real project.

What you get

• A verdict from the reviewer on every pull request the builder opens, shown on the ticket with its review rounds.
• Acceptance checks per milestone, written by you in the spec, to read the pull request against.
• A chance to catch gaps: issues the reviewer finds outside the ticket become a new ticket instead of being dropped.
• A record of every choice the crew made on its own, kept in the Assumptions fold with the tickets it touches and the builder that made it.
• A record of every answer you gave in the Decisions fold, including merge approvals if your project waits for your yes.
• A standup report, top right on the Crew page, that lists what is done, in review and blocked, with pull request links.

When something else fits

• If you want the crew to stop before every merge, the example project that waited for the person’s yes before each one shows that setup. The Crew page shows what you chose.
• If a docs change is a single quick edit, you can make it yourself without handing it to the crew.

Related