Template

Behaviour Definition Template

A structure for describing one piece of work before it is implemented, so that what you asked for and what you check against are the same thing. It follows the opening phases of PDAID: purpose, behaviour, clarifications, context and constraints.

To keep a copy, use your browser's print option — the page is formatted to print without the site navigation.

The template

Purpose: Why this piece of work exists, as an outcome rather than a feature. One sentence.
Behaviour: What should visibly happen, from the point of view of someone using the software. Observable, and checkable by someone who was not part of the conversation. Avoid describing how it works internally.
Clarifications: The decisions that would otherwise be left to the AI, written as settled answers rather than open questions. Empty and missing values, duplicates, ordering, limits, what happens when something fails.
Context: The part of the existing project this belongs to, and anything about the current state that affects it.
Constraints: What must not change: files and areas that are off limits, behaviour that must survive, dependencies that must not be added.
Acceptance checks: What you will look at to decide whether this worked. One line per check, drawn from the behaviour and clarifications above. Written before implementation, not after.

A completed example

Filled in for one small change, to show the level of detail each field wants.

Purpose: People need to correct a mistyped email address themselves instead of asking an administrator.
Behaviour: On the account page the user sees their current email address, enters a new one, confirms their password, and is told the change has been saved. The new address is then shown on the page and is what they sign in with.
Clarifications: An address already used by another account is rejected with a message. Invalid formats are rejected before saving. The old address is notified of the change. The change takes effect immediately. Three failed password attempts trigger the existing lockout.
Context: The account page and the existing user table. Sign-in already uses the email address as the identifier.
Constraints: Do not alter the sign-in flow, the password rules or the account page layout. No new dependencies. No change to the user table structure beyond the stored address.
Acceptance checks: Change an address successfully and see the confirmation.
The new address is shown on the account page afterwards.
Signing out and back in with the new address works.
An address already in use is rejected with a message.
An invalid format is rejected.
A wrong password does not change the address.
The old address receives a notification.
Existing users can still sign in, and the password rules are unchanged.

Using it well

Two habits make the difference between a template that helps and one that becomes paperwork.

Write the acceptance checks before the work is requested. They are much harder to write honestly once you have a result in front of you, and writing them early frequently exposes a clarification you had not settled.

Keep it proportionate. For a small change, each field may be a single line and the whole thing takes two minutes. If filling it in takes longer than the work itself, the piece of work is probably too small to warrant it — or too large to attempt in one go.