Write the Ticket You'd Want to Receive

Most teams treat their issue tracker as a place where work goes to be recorded. The good ones treat it as a place where work is communicated. The difference shows up in every ticket: a recorded ticket says “fix the thing”; a communicated ticket tells the next person what’s broken, how to see it, what “done” looks like, and where it fits. I got religion about this writing and standardizing tickets for a team, and the lesson is simple enough to fit on a sticky note: write the ticket you’d want to be handed cold.

The cold-pickup test

Here’s the test I apply to every ticket I write: if someone who wasn’t in the conversation picks this up in three weeks, with none of the context currently in my head, can they do it? That’s not a high bar in principle and almost no tickets clear it in practice, because we write them with all the context loaded and assume it’ll still be there. It won’t be — not for a teammate, and not for you in a month.

A ticket is a message to a stranger, and the stranger is often future-you. Write it so that person can act without finding you first.

Clearing the cold-pickup test usually just means including: what’s actually wrong (or what outcome is wanted), enough to reproduce or locate it, what “done” concretely means, and links to the relevant context. None of that is exotic. It’s just the stuff we leave out because, right now, we already know it.

Conventions are a contract, and consistency is the point

Teams accrete conventions — default issue type, the labels that go on everything, the component something belongs to — and it’s tempting to treat them as bureaucratic overhead. They’re not; they’re a contract that makes the tracker queryable. If every relevant ticket carries the same label, “show me all of these” is one filter. If half of them carry it and half don’t, that filter lies to you, and a filter you can’t trust is worse than no filter because you’ll believe it.

A small, sharp detail from doing this: the matching is usually exact and case-sensitive. A label that’s almost the agreed string — a near-duplicate component, a slightly different capitalization — silently falls out of every query built on the real one. The consistency isn’t pedantry; it’s the difference between conventions that aggregate and conventions that fragment. Match the string exactly, or you’ve quietly created a second bucket nobody searches.

The status workflow is a shared language

A defined set of statuses — and the legal transitions between them — is the team’s shared vocabulary for “where is this.” When everyone agrees what “ready for review” versus “in review” versus “ready for QA” mean, the board becomes a real-time picture of the work that doesn’t require a standup to decode. When statuses are vague or everyone uses them differently, the board is decoration and you’re back to asking people.

The value isn’t the specific stages — every team’s flow differs — it’s that the stages are agreed and meaningful. A status that anyone interprets differently is worse than no status, because it creates false confidence: the board says “in review” and three people picture three different realities. Define them once, and the workflow carries information instead of just color.

Linking is how work stays traceable

The other thing conventions buy you is traceability — the ability to walk from a small task up to the larger goal it serves, and back down. When tickets are properly linked into whatever hierarchy your team uses (a task to its feature, a feature to its initiative), two questions become answerable that are otherwise miserable: “why are we doing this?” (walk up) and “what’s left for this goal?” (walk down). Unlinked tickets are orphans — individually fine, collectively impossible to reason about. The few seconds to set the parent link is what makes the whole tree navigable later.

Conventions live in writing, or they don’t live

The last piece: none of this survives on tribal knowledge. “We always put this label on those” is a convention exactly until the person who knows it is on vacation, and then it’s a coin flip. Write the conventions down — the defaults, the status meanings, the linking rules — somewhere the team and any tooling can read them. That’s the same documentation-is-infrastructure instinct applied to process: an unwritten convention is a single point of failure wearing a friendly face.

It pays off twice over now that agents are doing real work, because a written convention is something you can hand a tool to follow consistently — the tracker conventions become machine-readable guardrails, not just human etiquette.

None of this is glamorous, and that’s the tell that it’s real teamwork infrastructure. A good ticket respects the time of whoever reads it next; consistent conventions make the whole tracker answer questions instead of just storing rows. Write the ticket you’d want to receive, and standardize the small stuff so the board can be trusted. It pairs with keeping work in small, well-scoped slices — a tight ticket and a tight slice are the same discipline. If your tracker has become a write-only graveyard and you want to dig out, I’m easy to reach.