Coroid does not start building from your sentence. It first turns your request into a specification: a statement of what will be built, what is explicitly out of scope, and the acceptance criteria that decide whether the work succeeded.
This is the highest-leverage part of the system. Everything downstream — the plan, the code, the tests, the verification verdict — is derived from it.
Why the extra step
An instruction like "add caching to the user lookup" has at least four reasonable implementations and no definition of done. An agent will pick one. Whether it picks yours is luck.
The specification makes that choice explicit before anyone spends a run on it, at the point where changing your mind is free.
It also gives verification something to test against. Without acceptance criteria, "did this work?" collapses into "do the tests still pass?", which is a much weaker question.
What a specification contains
| Part | What it answers |
|---|---|
| Scope | What will change |
| Out of scope | What deliberately will not, so the change does not sprawl |
| Acceptance criteria | How anyone can tell it worked |
| Context | Constraints, conventions, and prior decisions that apply |
You can read and edit it on the task's Specification tab before execution starts.
What makes acceptance criteria good
They must be checkable by someone who was not in the conversation.
Weak:
Caching works correctly and performance is improved.Strong:
- Repeated lookups for the same user id within 60s hit the cache, verified
by a test asserting the data source is called once across two lookups.
- Cache entries are invalidated when the user record is updated.
- A cache miss behaves identically to today, including error handling.
- No change to the public signature of `getUser`.The second version tells the developer agent what to build, tells the QA agent what to test, and tells you what to check on the pull request. The first tells nobody anything.
Scope lines matter as much as criteria
The most common cause of an oversized pull request is not an agent exceeding its brief — it is a specification that never said where the brief ended.
If you do not want the surrounding module refactored while it is in there, say so. "Do not change the call sites" is a legitimate and useful line.
When you disagree with it
Edit it. The specification is a working document up until execution begins, and correcting it is far cheaper than correcting the code that would have come from it.
If the specification reveals that the work is really two pieces of work, split it into two tasks. One task should end in one pull request that one person can review in one sitting.
Where it goes next
For anything beyond a small change the specification becomes a plan — see Tasks, plans, sprints and lanes — which you also approve before code is written.