“Add invite links to the team page” is a fine sentence to say to a colleague. They will ask three questions, infer four things from the codebase, and come back with something close. Said to a coding agent, the same sentence produces a plausible implementation of whichever interpretation the sampling landed on, at a speed that makes the mistake expensive.
Ambiguity used to be cheap
When implementation was slow, ambiguity resolved itself along the way. You discovered the open questions by hitting them, and the cost of discovery was folded into the cost of typing. Agents removed the typing cost and left the ambiguity exactly where it was, which means the questions now surface after the code exists, in review, at the worst possible time.
The fix is older than agents: write down what you are about to build before building it.
The smallest useful specification
We resisted heavyweight PRDs for a long time, and small fixes still get a short task specification instead. But for anything with more than one moving part, we have converged on a minimum:
- Requirements with stable IDs.
REQ-invite-02means the same thing next week. Tasks reference it, evidence is recorded against it, and the draft PR lists it. - Acceptance criteria per requirement. Not a test plan, just the sentence that would let a stranger say “yes, that is done.”
- Explicit assumptions and open questions. An inferred requirement is marked inferred. An open question is a decision for a human, not a coin flip for the model.
- Sources. Where the requirement came from: a Linear issue, a pasted brief, a Slack thread. Attribution makes disputes short.
Revisions, not overwrites
Requirements change while the work runs. That is not a failure of planning; it is what learning looks like. The mistake is letting the change happen silently.
Every save of a PRD in AgentCrew is a new immutable revision. Plans reference the revision they were made against. If the revision changes while tasks are queued, dependent dispatch stops until someone has looked at the plan again. Evidence recorded against the old revision goes stale. The system does not decide whether the change matters; it makes sure a person does.
The plan must cover the spec
A task graph that leaves a requirement uncovered is a plan to ship an incomplete feature. So the validator rejects it: every requirement must be referenced by at least one task, dependencies must form a DAG, and the whole thing has to be within sane limits. Agents propose plans; the validator is the part of the process that does not get tired.
Do it by hand first
If you use a single agent in a terminal, you can still do all of this in a Markdown file. Number the requirements. Write the acceptance sentence. Paste the file at the top of every session. You will notice two things: the agent asks better questions, and you catch your own ambiguity before the model does.