Worked example
The invitation specification
Settle permissions, duplicates, and the delivery boundary before writing the invitation flow.
Example specification · Workspace invitations
Invite a colleague into this workspace
- Decision owner
- Product Manager, with the engineering pair and QA.
- User outcome
- A workspace administrator can record an invitation for a colleague without giving another workspace access to it.
- This increment
- Authorize the request and store a pending invitation. Email delivery and invitation acceptance are separate increments.
Decisions made before generation
Resolve the signed-in person’s membership in the requested workspace on the server. An administrator role in a different workspace grants no permission here. Normalize the email address using the application’s existing convention.
For an identical workspace and normalized email, return the existing pending invitation. Do not create a second row or extend its expiry. An expired invitation needs an explicit replacement action; this increment reports that condition for the caller to handle.
Acceptance checks
| Given | Expected behavior |
|---|---|
| Administrator in workspace A, new email | Create one pending invitation owned by A. |
| Administrator targets an email already belonging to A | Report that the colleague is already a member; create no invitation. |
| Member without administrator permission in A | Deny the request; store nothing. |
| Administrator in A targeting workspace B | Deny the request; store nothing in B. |
| Two simultaneous requests for the same pending invitation | Return the same invitation; retain one record. |
| An existing invitation has expired | Report that replacement is required; retain the existing record. |
Before the pair starts
Confirm the existing API response conventions and record the exact statuses and response fields in the ticket. Locate the membership check, persistence transaction, and uniqueness constraint. Assign the first engineer to implementation and the second to challenge the acceptance cases; switch roles on the next increment.
What closes this increment
A reviewer can trace each check to the agreed behavior and inspect its result. The interface says “invitation recorded” until delivery has its own evidence. An unresolved permission or duplicate decision returns to the pair before generation continues.
Use this with Run a deep standup, then return to Execute.