Skip to content

Writing a ticket

A ticket that codeably works on is read as free text, so any ticket a person can understand will do. The shape below is the one the framework files itself when a design conversation is approved, and it's the one that reads best: for the team reviewing the ticket, and for the run that derives a spec from it.

The template

Copy this into the ticket's description and replace each part:

One sentence saying what is true once this is done.

## Why
- The reason this is worth doing, and what the choices behind it are.

## What changes
The behaviour, screens or interfaces that change, in a few sentences.

## Acceptance criteria
- The export lists every order of the selected month
- GIVEN an order without a customer WHEN the export runs THEN the order is listed with an empty customer column

## Out of scope
What this ticket deliberately leaves out, so nobody builds it by accident.
  • The first line is the goal. It has no heading. Say what is true afterwards, not what to do.
  • Why holds the reasons. A reviewer who disagrees with one can say so before any code exists.
  • What changes says what a user or a caller will notice. It doesn't say how to build it.
  • Acceptance criteria is one list item per criterion. When a criterion has a trigger and an observable result, write it as one line in plain words: GIVEN the starting point (optional), WHEN the trigger, THEN the result. Keep each criterion on its own line and don't nest WHEN and THEN as sub-items.
  • Out of scope names what is left for later, so the run doesn't take it on.

Why there is no steps section

A ticket says what is wanted, not how to get there. The run works out the steps from the repository it reads. When a ticket lists steps, each one is read as something the result must show, and a correct change that took a different route fails its own ticket.

A criterion is an outcome

Each acceptance criterion says what is true once the work is done: what a user sees, what a caller gets back, what a command prints. A rule about the shape of the code is not one, however narrow you make it: the size of functions, classes or files, line length, indentation and wrapping, naming conventions. When a ticket lists such a rule among its criteria, the run carries it as a step of the work and says so, instead of holding the result to it. A size rule is enforced only where the project's principles declare it as a limit. Visual design values from a reference (a colour, a spacing) and a named change such as "rename OrderList to OrderTable" are outcomes and stay criteria.

A ticket that has its own Done when (or Definition of done) list gets that list as the verdict, even when the run cuts the ticket into a single spec: each item becomes a done line of the spec that does that work, as specific as you wrote it, wherever the diff or a command can show it. An item about how to work (where a branch lives, what not to push) is not a done line; the spec's agent still reads it as part of the ticket. The review of the cut reports a spec set that drops one of those outcomes, quoting the ticket, so the outcome you wrote down is the one the run is held to.

What is read as items

Only the list under Acceptance criteria is read item by item. Each list item is one criterion the run is held to, and the pull request reports against each one. An indented line under an item belongs to that item. Prose, comments and code under the heading aren't criteria. The rest of the ticket is read as text.

On Azure DevOps, a ticket's Acceptance Criteria field takes precedence when it's filled in. One criterion per line there.

A bug ticket keeps its own shape: what is wrong, and what correct looks like. Its criteria go under the same Acceptance criteria heading, one list item each.