Anatomy of a Good Ticket

Most tickets are bad. They're vague titles — "fix login bug," "update dashboard," "backend work" — with no description, no acceptance criteria, and no context for anyone other than the person who wrote them. These tickets create the illusion of tracking while actually tracking nothing useful.

A good ticket has three parts:

• Title as outcome. The title states what will be true when the work is done, not what activity will happen. "Users can reset password via email" is an outcome. "Work on password stuff" is activity. The difference matters because outcome-oriented titles are testable — you can look at the finished work and ask "is this true?"
• Description as why. The description explains why this work matters and provides enough context for someone unfamiliar to understand the decision. Not a novel — two to three sentences that answer "why now?" and "what's the user impact?"
• Acceptance criteria as what. A short list of concrete, testable conditions that define "done." Not "it should work well" — but "the endpoint returns a 200 with a valid token, a 401 with expired credentials, and a 429 after 5 failed attempts in 60 seconds."

The test for a good ticket is the pick-up test: could an engineer who wasn't in the meeting where this was discussed pick it up and deliver it without asking clarifying questions? If the answer is no, the ticket isn't done — it's a placeholder.

Acceptance criteria are the most skipped part of a ticket and the most expensive to skip. Without them, "done" is whatever the engineer who worked on it thinks it means — which may not match what the product manager expected, what QA will test against, or what the customer actually needs.

Good acceptance criteria are concrete and testable. "The search should be fast" is not an acceptance criterion — it's a hope. "Search results return in under 200ms for queries up to 1,000 records" is testable. "The form should handle errors gracefully" is vague. "The form displays a red inline error message when the email field is empty and the user clicks Submit" is specific enough to build and verify against.

Acceptance criteria should be agreed upon before work starts, not written after. When an engineer and a product manager align on criteria before the first line of code, they're aligning on scope. Without that alignment, the engineer builds what they understood, the PM expected something different, and the ticket bounces back — costing both of them time and eroding trust. Writing acceptance criteria upfront takes 10 minutes. Reworking a misunderstood feature takes days.

The description is the source of truth. Comments are the conversation about it. Mixing them up is how tickets become unreadable.

The description should contain everything someone needs to understand the work: the context, the requirements, the acceptance criteria, and any relevant links. It gets written once (and updated if scope changes). It's the part you read first when you pick up a ticket, and it should answer your questions without requiring you to scroll through 47 comments.

Comments are for discussion that happens during the work: clarifying questions, scope negotiations, status updates, review feedback. Comments are append-only and chronological — they capture the conversation, not the conclusion. When a comment thread resolves a question that changes the requirements, the answer goes back into the description. The description gets edited; the comment stays as the audit trail of how the decision was reached.

Teams that dump everything into comments end up with tickets where the actual requirements are buried in comment #23, sandwiched between a status update and an emoji reaction. The engineer who picks up the ticket has to read the entire thread to reconstruct the current state. That's not coordination — it's archaeology.