Writing useful tickets
A ticket is a small contract between whoever wants the work and whoever will do it. This page is about how to write one that stays useful weeks after it’s filed and doesn’t need a meeting to interpret.
Recommended default
Section titled “Recommended default”A useful ticket has six things — nothing more:
- Title — the outcome, phrased as what the user or system can now do. “Users can reset their password by email”, not “Add password reset endpoint”.
- Why — one or two sentences on the outcome. What changes when this ships, and for whom.
- Acceptance criteria — observable outcomes that make “done” unambiguous. Three to seven bullets. If a tester can’t check it, rewrite it.
- Named edge cases — the two or three cases that would otherwise come back as questions. Not every case; the ones that shape the solution.
- Links, not dumps — design mocks, specs, related tickets. Paste the link, not the content.
- Size — reviewable in one sitting and revertible as one unit, even if that spans a stacked PR or a flagged rollout. If it isn’t, split it before it’s picked up.
Leave the how out unless a specific constraint (compliance, a downstream contract, a mentoring intent) narrows it.
Why this is the default
Section titled “Why this is the default”Tickets are read more than they’re written — often by someone who wasn’t in the conversation that created them. Every field above answers a question the reader will otherwise ask: what problem, for whom, how do I know I’m done, what have you thought about, where’s the context, is this one thing? Miss one, and the ticket generates a Slack thread instead of finishing.
The title is the highest-leverage line. Outcome-phrased titles force the writer to name what the work is for — and they read cleanly on a board, in a standup, and in six months when someone traces history. The reader who benefits most is often the reviewer: code review opens with the ticket, and a title they can’t parse is a review that starts with a question.
Common mistakes or tradeoffs
Section titled “Common mistakes or tradeoffs”- Task tickets. “Update the schema” isn’t a ticket, it’s a step. Ticket the outcome; the step is a comment on the PR.
- Status tickets. “Investigate slow queries” has no done condition. Either give it one (“know within a week whether X is the cause”) or make it a spike with a timebox.
- Design docs disguised as tickets. If the what runs three screens and names classes, it’s a design doc. Link to it; keep the ticket short.
- Acceptance criteria as tests. “Unit test covers reset flow” isn’t an outcome. Test coverage is a how; the outcome is the flow working.
- Everything in one ticket. A ticket that’s actually two is refined twice, reviewed twice, and blocked twice as often. Split first, refine second.
- Copying the ticket from a spec. Specs describe systems; tickets describe changes. If the ticket reads like a spec section, it’s the wrong shape.
Step by step
Section titled “Step by step”- Start with the outcome. Write the title as the state of the world when this ships.
- Write the why in two sentences. Who benefits, and how you’ll know.
- List acceptance criteria as observable outcomes. If a tester can’t verify it, rewrite it.
- Name the edge cases you already know matter. Stop before you name every case.
- Add links, not content. Design, spec, related tickets — one line each.
- Check the size. Reviewable in one sitting, revertible as one unit — even if that spans a stacked PR or a flagged rollout. If not, split it now.