▲ Agent-based development
Refinement agent: criteria an agent can verify.
By César Soto · 6 min read
▲ In this article
▲ In short
- A refinement agent reads the requirement against the real code and asks the product owner whatever is missing for the issue to be well defined.
- The result is an issue with acceptance criteria that can be checked with evidence, and the product owner approves it before anything is built.
- Those same criteria are what the acceptance agent verifies at the end, so an ambiguous criterion gets fixed at the start, where it costs one question.
When I wrote about an acceptance agent that checks every PR against its criteria, the first question I got was what happens if a criterion is ambiguous or incomplete. The answer sits one step earlier in the process, in an agent that refines the requirement with the product owner. Here is how it works, with an example written for this article.
What happens if an acceptance criterion is ambiguous or incomplete?
An ambiguous criterion gets fixed before building, because afterwards nobody catches it. The acceptance agent checks what the criterion says. If the criterion says little, the PR passes review and the gap shows up when QA or a customer finds it.
In our process, before a requirement reaches the build stage it goes through a refinement agent. It analyzes the current code and the requirement, and asks the product owner questions until the issue is well defined.
Repeats until no gaps are left.
What is a refinement agent?
Its work ends when the issue can be built without guessing. The conversation that used to happen mid-sprint, when a developer ran into the doubt, now happens before starting and stays written in the issue.
Why does the agent read the code before asking?
Because the best questions come from the real system. A requirement is written with the main case in mind, and the code holds everything else: the roles that exist, the filters that screen already has, the exporter someone built last year.
Take this requirement: administrators must be able to export the sales report. Read alone, it looks complete. Read against the code, it opens four questions.
| What the agent finds in the code | What it asks the product owner |
|---|---|
| The report has date and branch filters | Does the export respect the active filters or return everything? |
| There are two administrator roles: account and branch | Which of the two can export? |
| A CSV exporter already exists in the customers module | Do we reuse that format or is Excel needed? |
| The report can exceed 100,000 rows | What should happen with a large report: wait, background or a limit? |
None of the four is technical. They are product decisions the requirement left implicit, and whoever built it would otherwise have made them without telling anyone.
What does the issue look like after refinement?
It has context, numbered criteria and a list of what will not be done. With the product owner's answers, the one-line requirement becomes this.
Export the sales report to CSV
Context
Account administrators need to take sales data into
their spreadsheet.
Acceptance criteria
1. The "Export" button appears only for the account
administrator role.
2. The file respects the active date and branch filters.
3. The CSV has the same columns as the table,
in the same order.
4. Above 10,000 rows, the export runs in the background
and sends an email when it finishes.
5. A branch administrator does not see the button and
the endpoint returns 403.
Out of scope
Excel format. Scheduled exports.
Every criterion comes from an answer. The Out of scope section matters as much as the criteria: it tells the building agent where to stop, and the acceptance agent what not to demand.
What makes a criterion verifiable by an agent?
A criterion is verifiable when it can be checked with evidence, in the code or by running the application. If calling it done takes an opinion, it is still a wish.
| As it arrives | As it ends up | Evidence the acceptance agent looks for |
|---|---|---|
| The export must be fast | Above 10,000 rows it runs in the background and sends an email | A job in the queue and the email sent when it finishes |
| Only administrators export | A branch administrator does not see the button and the endpoint returns 403 | The condition in the interface and an endpoint test with that role |
| The file must match the report | The CSV has the same columns as the table, in the same order, with the active filters | A test comparing the columns and the filtered rows |
What changes for the product owner?
The product owner moves from drafting the whole requirement to answering precise questions and deciding the scope. Their judgment stays at the center of the process: the agent points at the gaps, and only the product owner knows what the business needs in each one.
- They decide with the system in view. Questions arrive with what already exists in the code, so the decision accounts for the real roles, filters and limits.
- They approve before anything is built. The refined issue goes through their approval, which is the first human gate in the process.
- They get what they asked for. The criteria they approved are the same ones the acceptance agent checks in the PR.
“An ambiguous criterion costs one question at the start and a returned requirement at the end.”
How does it connect to the acceptance agent?
Both agents work on the same list. The refinement agent leaves the criteria written at the start, and the acceptance agent looks for evidence of each one at the end, before the PR reaches a person. I describe that second agent in what a harness is.
It is the same rule I use for agents in production: the agent proposes and someone with authority decides. Here the agent proposes the issue and the product owner approves it. PeakSyn's method shows where each gate sits.
Where do you start?
- Take the last requirements QA sent back. Note which question, asked in time, would have prevented each one.
- Give the agent the requirement and the code. Without the code, its questions will be the generic ones from any template.
- Ask it for questions before a draft. The issue is written after the answers.
- Require numbered criteria and an out-of-scope section. Each criterion with the evidence that would prove it.
- Leave approval with the product owner. Nothing moves to build without it.
If you want to look at how this step would work in your team, you can book a 30-minute conversation.
Frequently asked questions
Does the refinement agent replace the product owner?
No. The agent finds the gaps and drafts; scope and priority decisions belong to the product owner, and the issue does not move to build without their approval.
What if the product owner does not have the answer to a question?
The requirement stays in refinement until they do, or that part moves to out of scope. Both outcomes are better than building on an assumption.
Is refinement useful without an acceptance agent?
Yes. An issue with verifiable criteria helps a developer and QA just the same. With an acceptance agent the benefit grows, because those criteria get checked on every PR.
Does it depend on a specific tool?
No. It takes an agent that can read the repository and a place where requirements live, which in our case is Linear. The same setup works with other issue trackers.
References
Want to apply it in your team? Let's talk for 30 minutes.
Free, on video, with César Soto.
Book a conversation