How to link decisions to Jira tickets: 5 options compared

Most teams on Jira have the same ticket somewhere: the one whose description says one thing, whose comments say another, and whose actual scope was settled in a Slack thread nobody linked. The ticket is the unit of work. The decision that shaped it lives somewhere else.

This post covers how to link decisions to Jira tickets so they stay attached: five options, a step-by-step for the Confluence and Jira route most teams already have, and a naming convention that makes decisions traceable from ticket to PR.

Why decisions get detached from tickets

Jira is built to track work, and work has a lifecycle: open, in progress, done. Decisions don't. "We're shipping v1 without SSO" doesn't get closed; it stays in force until someone reverses it. So decisions end up in the places Jira doesn't model well:

• Ticket comments. The call gets made in comment 14 of 30. Nobody reads past comment 3.
• Slack and meetings. The conversation happens off-ticket. Maybe someone pastes a summary back. Usually not.
• Edited descriptions. Someone updates the acceptance criteria to match the new call. The reason, and the fact that it changed, disappear.
• Closed tickets. The decision was recorded on a story that shipped. Six months later, a new story contradicts it, and nobody searches closed work.

The result is decision drift: the ticket, the code, and the decision quietly disagree.

The options

1. Jira custom fields and work item links

Jira admins can create a custom field (a paragraph field called "Decision," say) and add it to the screens your team uses. Jira also supports linking work items to each other, to Confluence pages, and to web links, and admins can add a custom link type such as "is decided by / decides."

(Atlassian now calls issues "work items" in Jira Cloud. Same thing.)

Good for: small teams who live entirely in Jira. Falls short: a field holds a sentence, not the reasoning, the rejected options, or a status. And one decision often affects several tickets, so it ends up copied into each.

2. Confluence decision pages linked to Jira

One Confluence page per decision, linked to every work item it affects. Confluence's Jira work items macro shows the linked tickets (with live status) on the decision page, and the work item links point back. This is the setup I'd recommend for any team already on Atlassian. Step-by-step below.

Good for: teams on Jira and Confluence. Falls short: someone still has to notice the decision and file the page.

3. Linear project documents

If you've moved off Jira to Linear, project documents give each project a place for specs and decisions, and you can reference documents from issue descriptions and comments with @. It's the same pattern as option 2 with less setup.

Good for: Linear teams. Falls short: decisions are scoped to a project, so cross-project calls need a home of their own.

4. ADR files in the repo, referenced by ticket key

For architecture decisions, keep ADRs in doc/adr and reference both IDs in the work. Jira picks up development activity when you reference work item keys in branch names, commit messages, and PR titles, so a PR titled PAY-412: switch amounts to cents (ADR-0007) shows up on the ticket and names the decision.

Good for: engineering decisions that should be reviewed like code. Falls short: PMs and other teams rarely read the repo, and product calls don't belong in doc/adr.

5. Automatic capture with Lockstep

Lockstep is open source (Apache-2.0) and drafts decisions from where they're made: Slack, Notion, Jira ticket comments and acceptance-criteria changes, Confluence, Google Docs, and GitHub PRs. Each decision goes to its owner for one-click approval, stays linked back to the ticket it came from, and gets briefed to engineers and AI coding agents over MCP. A PR check flags changes that conflict with an approved decision (it warns by default; blocking is opt-in). The Jira connection is read-only, so it doesn't write to your tickets.

Good for: teams where decisions happen faster than anyone files them. Falls short: it's another tool to adopt, and Slack capture is the most mature source today.

Step by step: a Jira decision log with Confluence

This uses the page template from the Confluence decision log template. If you want the generic version, start with the decision log template.

1. Create the decision page. One page per decision, titled with an ID and the verdict: DEC-014: Ship v1 without SSO. Add the Page Properties table (status, owner, decided on, review by) and the label decision.
2. Add the affected tickets to the page. Under "What this changes," type /jira and pick Jira work items, or paste a work item URL or a JQL filter URL. Confluence converts it to the macro, so the page shows every affected ticket and its current status.
3. Link the page from each work item. On each ticket, use the link option to add the Confluence page (or a web link to it); Jira supports page and web links alongside work item links. When a page links to Jira work items, Confluence shows a Jira Links button at the top of the page, so readers can jump either way.
4. Optional: a link type for decisions. Ask a Jira admin to add a link type under Settings, Work items, Work item linking, so decision links don't hide among "relates to."
5. Put the ID in the ticket. Add Decision: DEC-014 to the description or your custom field, so it shows up in search.
6. Supersede, don't edit. When the call changes, create DEC-031, mark DEC-014 Superseded with a link to it, and re-link the affected tickets.

A convention for decision IDs in tickets and PRs

The links only help if people can follow them. A simple convention:

• One ID format, everywhere. DEC-### for product and cross-team decisions, ADR-#### for architecture. Never reuse a number.
• Ticket: the description gets a line Decision: DEC-014 (link).
• Branch and PR title: lead with the Jira key, so Jira's development panel picks it up: PAY-412-drop-sso, PAY-412: remove SSO from v1 scope.
• PR description: a line Implements: DEC-014 or Conflicts with: DEC-009, superseded by DEC-031.
• Commit message: the Jira key, optionally the decision ID.

Now a reviewer sees which decision a PR implements, and anyone on the ticket can follow it to the reasoning and the code.

Comparison

Option	Holds the reasoning	Linked to tickets	Reaches PRs	Who files it
Jira custom field / links	One sentence	Yes, native	Via Jira key	Someone, by hand
Confluence page + Jira macro	Yes	Yes, both ways	Via ID convention	Someone, by hand
Linear project documents	Yes	Yes, @ references	Via issue ID	Someone, by hand
ADR files in repo	Yes	Via ticket key	Yes, reviewed in PRs	Engineer, by hand
Lockstep	Yes	Yes, back to source	PR check flags conflicts	Drafted automatically, owner approves

Where this breaks

Every option except the last depends on someone noticing that a decision was made and stopping to file it. The big calls get filed. The scope cut in a Slack thread doesn't, and that's the one that turns into a ticket contradicting itself. I wrote about why in engineering decision logs.

Start with the Confluence route and the ID convention this week. If you find the log is only catching the decisions people remembered, that's the gap Lockstep fills.