Skip to content

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.

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.

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.

  • 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.
  1. Start with the outcome. Write the title as the state of the world when this ships.
  2. Write the why in two sentences. Who benefits, and how you’ll know.
  3. List acceptance criteria as observable outcomes. If a tester can’t verify it, rewrite it.
  4. Name the edge cases you already know matter. Stop before you name every case.
  5. Add links, not content. Design, spec, related tickets — one line each.
  6. 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.