Skip to content
Easy AI How-To

AdvancedAgentsBuilding

The developer's new job: review the factory's artifacts before you merge

Part of the Software Factory series, a pattern by Greg Alton. The factory does the spec work, the tests, the code, the validation, and the review. You are the last station before merge. Your job isn't to write the code; it's to check the evidence the factory left behind.

Time
About 15 minutes
Checked
Tool
AGENTS.md format

If a button name on the screen does not match this guide, follow the action. These products rename buttons often. This is an advanced guide: it uses code, and each technical term is explained the first time it appears. Model names and prices change, so check the linked docs before you ship.

Steps

  1. Start from the Handoff comment

    Open the ticket's Handoff comment. It links everything: the PR, the review comment, the disposition report, the Plan, Test Results, and Execution Summary, the commits, and the changed files. If it's missing, the factory isn't done.

  2. Check the spec trail

    In the Plan, confirm every task maps to a requirement in the spec, and the Deviation section is "none" or explains a spec change you agree with. Code that does something the spec doesn't mention is a red flag.

  3. Check the test evidence

    In Test Results, each requirement should have a test, and each test should show a real RED before GREEN. Look for exact commands and counts (passed, failed, skipped). A skipped or deleted test needs a reason. Run the QA steps yourself on anything risky.

  4. Check the review and disposition

    On the PR, read the Code Review and Security Review comment, then the Review Disposition Report. Every finding should be Accepted (with a commit), Partial (with a follow-up ticket), or Rejected (with evidence). No finding should be left unaccounted for.

  5. Read the diff with that context

    Now read the diff. Because you know what the spec wanted and what the tests prove, you can focus on design, naming, and anything the tests can't catch. This is much faster than reviewing cold.

  6. Merge, or send it back down the line

    If every gate holds, merge. If not, leave a review comment saying which station failed (spec, tests, code, validation, or review) and let the factory run that station again.

Tips

  • Treat missing artifacts as a failed build. 'The agent said it's done' is not evidence.

  • Spot-check one RED → GREEN claim per PR by running the test on the base branch. It keeps the factory honest.

  • When you find a problem the factory missed, add a rule to AGENTS.md so it can't happen again. That's how the factory gets better.

Common questions

Doesn't this just move work to the developer?

It moves the developer from typing code to judging evidence. Reviewing a well-documented PR takes minutes, and you review every change with the spec and test proof in front of you.

Can I let the factory merge small changes?

The pattern says no. The merge gate is what keeps a human accountable for what ships.

What's the fastest way to adopt this?

Start with the AGENTS.md from part 2 and just the plan, code, and validate stations. Add the tracker and review stations once those run smoothly.

More guides

Occasional notes

Hear when a new guide is up

A short note when a guide is added. No account, and no emails until this form is connected to a real list.

Placeholder. This form is not connected to an email service. Nothing you type is saved or sent.