"Add a search box" is not a description of behaviour. It is the name of a thing you would like to exist.
The difference matters because the name is enough for the work to begin and not enough for it to be checked. You will get a search box. Whether it is the one you had in mind is a question neither of you can answer, because nothing was ever said that could be true or false.
What follows is the mechanics of closing that gap: what a behaviour statement is made of, how to improve one you have already written, and how to tell when it is finished.
Three parts, and the one that gets left out
A usable behaviour statement has a trigger, a response and a resulting state.
The trigger is what someone does, or what happens: a button is pressed, a form is submitted, a file finishes uploading, midnight passes. The response is what the software does about it. The resulting state is what is true afterwards that was not true before.
Most descriptions carry the first two and drop the third, and the third is where the disagreements live. "When the user clicks Cancel Booking, the booking is cancelled" has a trigger and a response and tells you almost nothing. Cancelled how? Is it gone from the list, or shown as cancelled? Can the slot be booked by someone else now? Does the user still see it in their history?
Adding the resulting state forces those out into the open:
When the user presses Cancel Booking and confirms, the booking is shown as Cancelled in their bookings list rather than removed, the time slot becomes available to others immediately, and the user is returned to the list with a confirmation message.
That is one sentence and it settles four things that would otherwise have been decided without you.
The same description, improved in stages
Take a feature request as it usually arrives.
Users should be able to search their documents.
This is a topic. Nothing in it can be checked. The first improvement is to say what someone actually does and sees.
The user types into a search box above the document list and sees only the documents that match.
Better — there is now a trigger and a visible response. But "match" is doing an enormous amount of unexamined work, so the second improvement is to say what matching means in terms someone could verify.
The user types into a search box above the document list. The list narrows to documents whose title contains what was typed, ignoring capitalisation. Typing "report" matches "Q3 Report" and "reporting-notes".
An example inside the description is worth more than another adjective. It converts a rule into something you can try.
The third improvement adds the resulting state and the boundaries of the change.
The user types into a search box above the document list. The list narrows to documents whose title contains what was typed, ignoring capitalisation — typing "report" matches "Q3 Report" and "reporting-notes". The list updates as they type. Clearing the box restores the full list. Sort order is unchanged by searching, and the search text is not remembered when the user leaves the page.
Compare that with where it started. The work went from one sentence you could not check to one paragraph you could hand to someone else, and every addition came from asking the same two questions: what would I see, and what is true afterwards.
Say what happens when it does not work
Descriptions overwhelmingly cover the case where everything goes right. That is the case least likely to cause you trouble.
For each behaviour you have described, there is usually a short list of ways it can fail to produce the happy result: nothing matches, the input is unusable, the thing you are acting on has changed underneath you, the operation cannot complete. Each of those is behaviour, and each will be invented for you if you do not state it.
For the search box, the honest version continues:
If nothing matches, the list area shows "No documents match that search" and the search box keeps its text and focus. If the user has no documents at all, the existing empty-state message is shown instead, and the search box is not displayed.
Notice that the second sentence describes a case most people would not have thought to mention, and that it produces a visibly different result from the first. Both are "nothing to show". Treating them as the same thing is the sort of decision that gets made silently and looks wrong to a user for reasons they cannot articulate.
Implementation words, and what they cost
Implementation language creeps into behaviour descriptions almost unnoticed. The tell-tale words are the ones that name a mechanism rather than a result: store, cache, index, validate, endpoint, modal, state, component, query.
"Search should query the database with a LIKE clause" is not behaviour. It is one way of producing behaviour, chosen before you established what the behaviour was, and it forecloses the part of the work AI genuinely does well.
There are two costs. The first is that you may have chosen badly — with ten documents almost anything works, and you have specified a mechanism without knowing whether it matters. The second is subtler: a description written in mechanism terms cannot be checked by looking at the software. You end up reading code to decide whether the code is right, which is exactly the position the description was supposed to save you from.
This is not a prohibition on ever saying anything technical. If a real constraint exists — it must use the existing search service, it must work without JavaScript — say so plainly, as a constraint, and keep it out of the behaviour. The test is whether you would actually mind if it were done another way. If you would not mind, do not say it.
Behaviour with nothing obvious to look at
Some work has no screen. A nightly job archives old records; a webhook receives data from another system; a file is processed after upload. The instinct is to describe these in mechanism terms because there seems to be nothing else available.
There is almost always something observable, and finding it is worth the two minutes. What is different afterwards that someone could point at? A record has moved from one state to another. A row appears in a log. A count changes. An email arrives. A file exists where it did not.
Each night, invoices that were paid more than twelve months ago are marked Archived. Archived invoices no longer appear in the default invoice list but are still found by searching for their number, and their totals are excluded from the current-year report. If the job cannot complete, nothing is marked and an entry is written to the error log.
No screen is mentioned, and every clause is checkable by someone who did not write it.
The moment an intention becomes accepted behaviour
There is a real difference between what you would like the software to do and what you have committed to. It is easy to blur, because both live in the same words.
An intention is provisional. You can revise it when the result arrives, and you will be tempted to, because the result is concrete and your intention was not. Accepted behaviour is what you decided before seeing the result and agreed to judge the result against. Once you have accepted it, a mismatch is a defect rather than a matter of opinion.
That distinction is the entire reason for writing behaviour down in advance. If the description is written afterwards, or quietly adjusted once you have seen what arrived, it cannot tell you anything — it will always be satisfied. The value is not in the words. It is in the words having been fixed before there was any pressure to bend them.
In practice this means being deliberate about the moment of acceptance. Write the behaviour, read it once for the failure cases, and treat it from then on as the thing that decides whether the work is finished. If you genuinely change your mind later, change the description explicitly and say that you have — which is very different from letting it drift to fit.
The behaviour definition template is a structure for doing this on one piece of work, and how to test code you didn't write is what happens next, once you have something to check against. If you have written a description and can feel that questions are still unanswered inside it, the technique for finding them is in the decisions to make before AI makes them for you.