A Jira ticket template engineers will still understand a year later

Open a Jira ticket from a year ago and read it as if you'd never seen it. Most say what to build ("Add retry to webhook sender") and stop there. The why (which customer hit the problem, what else was considered, what was ruled out) lived in a standup, a Slack thread or someone's head.

That's fine on the day the ticket is written, because everyone involved remembers. It stops being fine the moment someone new asks "why does it work like this?", because the ticket is often the only artifact that links the code back to a reason.

This post gives you a short Jira ticket template that keeps the reasoning attached to the work, plus variants for bugs and tech debt, how to make it the default in Jira, and a few habits that make tickets useful long after they're closed.

(A note on names: Jira now calls issues work items and projects spaces. We use "ticket" throughout, since that's what most teams still say.)

Why most Jira tickets don't age well

Tickets are written for the sprint, not for the archive. The person writing one is optimizing for "can the assignee start work tomorrow?", which is the right goal, but it leaves out three things a future reader needs:

• The trigger. What happened that made this worth doing now? A customer report, an incident, a metric, a strategy change?
• The alternatives. What other approaches were discussed, and why weren't they chosen? This is the part that stops the next person from "fixing" your deliberate trade-off.
• The decision and who made it. "We agreed on X" is only useful if you can tell where it was agreed and by whom.

None of these take long to write. They just need a slot in the template, because nobody adds a section that isn't there.

The template