BigBrain · how work is written up
A ticket an agent can build alone.
Agents pick up tickets and build them without asking anyone. That only works when the ticket says everything up front. This page is that format, and how a written ticket gets grouped, ordered, sized and handed to an agent.
AI helpers take to-do tickets and finish them without asking questions. That only works if each ticket says everything up front. This page shows how a ticket is written, grouped, ordered and sized, and how it gets to a helper.
Six sections, each with a budget
Every ticket body uses the same headings in the same order, whoever files it. Each has a word budget, because a ticket should read in five seconds. A Problem Statement that runs long is usually two tickets.
Every ticket uses the same headings in the same order. Each one has a word limit, so the whole ticket can be read in five seconds. If the problem takes a paragraph to explain, it is usually two tickets.
| Section | What it answers | Budget |
|---|---|---|
| Problem Statement | What is wrong. Design links and the incident behind it go here, not above it.What is wrong, plus any link to a design. | 50 words |
| Why | What is worse for a user or operator while it stays undone.Who is worse off until it is fixed. | 40 words |
| Definition of Done | What must be true to call it finished, one checkable line each.How you can tell it is finished. | 60 words, up to four lines |
| Solution | What will actually be done.What will be done. | 60 words, up to four lines |
| Action Items | Numbered steps the owner runs personally. Left out unless the ticket needs them.Steps only the owner can do. Usually absent. | Only when needed |
| Touches | The files the ticket will edit, one per line. Always last.The files it will change. Always last. | One file per line |
The title is under 60 characters and names the thing, not a sentence about it, with no ids or paths. Background that won't fit goes in a comment, never a seventh section.
The title is short and names the thing. Extra background goes in a comment, not in another section.
Touches: the files a ticket will edit
The Touches list is how two agents avoid editing the same file at once.
The file list is how two helpers avoid changing the same file at the same time.
- Two tickets that name the same file get a blocking link or a shared ticket both wait on. They never run side by side.If two tickets name the same file, one waits for the other.
- A ticket that names too many files is refused for unattended work and gets split instead.A ticket that changes too many files is too big to hand off, so it gets split.
Milestones and order
A milestone is one outcome, named for what it delivers. Tickets inside it are ordered by blocking links, not by prose.
A milestone is a group of tickets with one goal, named for what it delivers. Links between tickets set the order inside it.
- Every project has a Bugs milestone, sorted first, because bugs are worked before features.Every project has a Bugs milestone at the top, because bugs come before new features.
- Each new ticket is blocked by the one filed before it in the same milestone, so a set is filed in the order it should be built.Inside a milestone, each new ticket waits for the one filed before it, so tickets are filed in the order they should be built.
- Milestones are not linked to each other. The owner picks which one to start.Milestones don't wait on each other. The owner picks which one to start.
How a blocking link turns a list into a tree is under blocks edge.
How a blocking link puts tickets in order is under blocks edge.
Forecasts
A ticket's size comes from measured runs of comparable work, not from a guess in hours.
A ticket's size comes from how long similar work really took, not from a guess.
- One point is a fixed slice of predicted minutes, and the forecast carries the range it was drawn from.One point always stands for the same amount of predicted time, and the forecast shows a range.
- "Unknown" is a valid answer when there is no comparable work. It is never filled in with a default, and it does not clear a ticket for unattended work."Unknown" is an honest answer when nothing similar has been done. It is never swapped for a made-up number, and it doesn't let a helper start the ticket on its own.
How a ticket reaches an agent
The board's columns are the approval.
Moving a ticket between columns is how the owner says go.
- Backlog means not yet. Every filing route lands there, and nothing reads it.Backlog means not yet. New tickets land there and wait.
- Moving a ticket to Todo starts it: a sweep queues every unblocked ticket there.Moving a ticket to Todo starts it.
- Before the run, a trust level decides whether it may change anything or only read and assess. Untrusted work runs read-only.Before it starts, a check decides whether the helper may change anything or only look and report. Work nobody vouched for can only look.
What decides the verdict is under trust level.
What decides it is under trust level.
Start and finish
Two skills bracket every ticket worked by hand.
Two shortcuts begin and end each ticket.
- /start drops blocked and running tickets and offers at most three, each marked for the owner or an agent./start offers at most three tickets, each marked for the owner or a helper.
- /finish runs the tests, commits once, closes the ticket with what changed, why and how it was checked, then walks the blocking links to the next one./finish runs the checks, saves the work once, closes the ticket and moves on to the ticket it was holding up.
How the owner uses them day to day is on Practice.
How the owner uses them is on Practice.
Names, ids and figures taken out.
Private details have been taken out.