nav[aria-label="Primary Navigation"] { padding: 0; & ul { list-style: none; width: 100%; display: flex; flex-direction: row; justify-content: start; align-items: start; gap: 30px; padding: 0; & li { margin: 0; } & ul li { list-style: none; } } }

Best practice for tracking key decisions and major changes in Jira Cloud?

Lucian Irimie_tzkm65

Hi everyone,

In larger programmes, we’re finding that important delivery and architecture decisions often get buried in comments or spread across multiple issues and Confluence pages.

A few months later, it becomes hard to understand:

why a certain option was chosen
who approved a major scope or design change
what alternatives were considered
what risks were discussed at the time

Jira’s change history shows what changed, but not always the reasoning behind it.

We’ve tried comments, labels, and linked Confluence pages, but over time the context still gets fragmented.

How are others handling this in practice?

Are there any simple patterns that have worked well without adding too much process overhead?

For example:

specific issue types for decisions
structured comment templates
automation rules
dashboards or saved filters
Confluence integration

Would really appreciate hearing what’s worked (or hasn’t worked) for you.

Thanks!

Comments

Garth Bond

I have the same challenges, so it would be great to hear other solutions from others that have solved this.

Stefan Draber_kwaltd

Hi @Lucian Irimie

in Confluence there are built-in macros for that: decisions and decision reports.

Thinking in terms of a workflow, I'd recommend to switch over to Confluence everytime you're about to make a decision, and document all the information you need to provide context for this decision, including the decision itself.

Then you can create a decision overview on an extra page with the decision report macro that consolidates all decisions made in a selected space, with individual filter criteria and so on.

Nowadays, in the age of AI, you could also think about creating a Rovo agent that crawls your tickets to find content that seems to be decisions, and to transfer this content including contextual information over to Confluence in something like a decision documentation.

Robert Eiser

This is a great question! I’m happy to share how we currently document changes to our Jira configuration, and I’d also love to learn how others approach this.

We use a dedicated Jira project (sorry, space...) to manage internal change requests. Any proposed modification to our Jira setup, such as adjustments to workflows in other projects, is initiated and tracked as a single issue within that change‑management project. All discussions, decisions, and approval steps happen directly on that issue so the full history stays in one place.

As part of our workflow, one of the final stages is Documentation, where we record the completed change in Confluence for future reference.

Looking forward to hearing how others handle this process.

All the best,
Robert

Lucian Irimie_tzkm65

Hi and thanks Stefan the Confluence decision macro is a good point.

One thing we’ve observed in delivery programmes is that teams often document decisions in Confluence, but the operational impact still lives in Jira (Epics, scope changes, design pivots).

The challenge becomes traceability between:
• the documented decision
• the Jira issues affected
• and the later delivery outcomes

Have you seen teams formalise the linking pattern between Confluence decisions and Jira work items? Or does it tend to rely on manual discipline?

Lucian Irimie_tzkm65

Thanks Garth, good to know it’s not just us.

In our case, the real issue shows up 3–6 months later when someone asks “why did we decide that?” and the reasoning is scattered across comments, meetings, and Confluence pages.

Have you tried anything structured (e.g. a specific issue type or template), or is it mostly informal documentation at the moment?

Lucian Irimie_tzkm65

Thanks Robert, that’s a very structured approach, especially using a dedicated project for configuration changes.

I like the idea of keeping the discussion and approval trail in a single issue.

In our case, some of the challenge shows up more on the delivery side (e.g. architectural choices, scope pivots within epics), where the decision isn’t necessarily a Jira configuration change but still has long-term impact.

Have you found a similar pattern works well for those types of programme-level decisions too, or do you handle them differently?

Appreciate you sharing your setup.

Alan Bruce

This is a great idea. I would love to have everything in one place vs shared with all of the other stories and epics.

Lucian Irimie_tzkm65

That’s exactly the tension we’ve seen as well. Once decisions are scattered across epics, stories and comments, they’re technically “recorded”, but not really retrievable.

Centralising them somewhere (whether in a dedicated project or structured Confluence space) seems to be the key.

The tricky part is keeping it lightweight enough that teams actually use it consistently.

Stefan Draber_kwaltd

To be really honest here: no, I've never seen a team mastering this challenge in a proper manner. But that's the same with all kind of documentation I guess

But I think this is due to the nature of things. At the point you're about to initiate the decision making process, you have to realize this and act accordingly in order to make it transparent and sustainable. Once you ensured this, it doesn't really matter what is being triggered then, whether it's a "Decision" issue type or a Confluence page or whatever.

I would try to set it up something like this:

1. Get a team/project agreement: whenever any type of decision is on the table, create a Confluence document in a "decision register". This could be supported for example by manual automations in Jira.

2. In this document, link the Jira ticket and provide context: options considered, risks identified, discussed with whom, approved by whom etc.

3. Create a central decision register per team/project/organization with a decision report, filtering the relevant scope.

(4. Later on, when you're resolving support tickets as "known issue", "works as designed" or "won't implement", you can simply link your decision documents to the support tickets)

As I said, the critical point is to recognize a decision when it arises and to maintain the discipline to act accordingly.

However, I'd be super curious if Rovo agents are already capable to solve or at least substantially support steps 1 and/or 2.

Sarah.wright

The Decision macro is available in Jira via comments, descriptions and paragraph fields. Knowing that you could use a comment. Create a sub-task (not a new work type for this) but a simple sub-task summary Decision on X. Description logs the decision.
You can use JQL to find them
comment ~ "\\\\{decision\\\\}"

If you need more long-form context create a manually triggered automation to create a confluence page using the Decision template and includes the link to the Jira item.
Assuming AI is in play, a Rovo agent called up via automation, when a page is published, analyze the page for decision-related content. The agent could do same on Jira items. Forge could add even more capability.

When viewing an item, generate the AI summary which may call out decisions.

Some degree of manual discipline will help. Ensure folks are aware that they are making impactful decisions and that need to be considerately logged. Use the method that works for the team that creates the least amount of overhead.

Sarah.wright

Screenshot 2026-02-20 at 8.51.19 AM.png Screenshot 2026-02-20 at 8.50.52 AM.png

Robert Eiser

Thanks Sarah! I was not aware of this feature.

Stephen.Lugton

We operate an architecture / design authority (DA).

For this we have a key design decision log in Confluence along with an ever expanding list of key design decision (KDD) documents - one key design decision per document. If we need further decisions on any particular topic we create a new KDD.

Every KDD has a page properties macro at the top with entries for:

Project
Status
Author
Decision Date
Decision Type

The Key Design Decision Log has a page properties report macro to surface the properties of the KDDs in one place.

Whenever we need to make a design decision we start off with an asynchronous update to give people a chance to read the KDD, if we need a more detailed presentation for the decision we follow this up with a time-boxed design authority meeting where everyone has a chance to ask questions, etc.

Whether or not we have a face to face meeting the KDD is updated with details of why the decision was made using the decision macro. All decisions are then picked up by a decision report macro on the KDD Log.

This adds a bit of process, but it keeps all design decisions together and gives us an audit trail.

Since the decision is in Confluence we can link it to Jira tickets.

For 'day-to-day' decisions we have a Jira sub-task 'decision', we just add one of these to any work item that needs a decision, to work with this, we have a dashboard that lists fields from all the decision sub-tasks for any specific project.

Stefan Draber_kwaltd

Thanks a lot Sarah, I didn't know the decision macro in Confluence neither. Unfortunately, the Confluence decision report is not able to report on these.

James Traxler_qxfeyh

It is indeed a conundrum... because a team tends to make many, many decisions, but it is only certain decisions that have further-reaching effects.

Usually it's only when someone asks the reason behind a decision that you need to know the why, so it's hard to know at the time of the decision whether you need to record the reasoning behind it.

So, the problem becomes, how to record decisions that are important enough to record, and to make that process easy enough so that people actually do it, and how to know if a decision warrants needing to record it.

For my team, so much of the discussion happens in messages over Slack... So, if someone later asks about a decision, we tend to look back over Slack for details, as well as searching in Jira tickets and Confluence pages. However, that is all a bit piecemeal.

Sorry, I don't have an answer!

David Cowley

What we try to do is ensure that the work item description is updated as the work evolves through the comments, so that the description always reflects the actual intended work. Depending on the scope of the deviation from the comments, this might result in any or all of the following:

updating the original description (and/or summary), possibly adding notes
closing the original ticket and creating one or more new tickets linked to the original
creating sub-tasks
splitting the original ticket into multiple tickets

Our user base has a tendency to include multiple issues in a single work item, and to make additional requests beyond the original scope of work in the comments. I don't think that scenario really fits what you're describing, but those are the techniques we're using.

Overall our goal is to prevent someone from needing to go back and read through all the comments in future. Descriptions are authoritative not comments.

Felipe Sozinho

Hi @Lucian Irimie ,

Something I have used that I thought worked well was to have an issue type called "Decision" and I have that added to every project I am in.

As mentioned throughout the comments, the real challenge is knowing which decisions are worth recording. And with a custom issue type we were able to ensure every decision was recorded in a structured format. For us it was

Summary - represents what needs to be decided on
Challenge/Issue - what is this decisions resolving/supporting
Additional Context - anything else the users wants to record that was relevant for the discussion
Options Considered - here we enforce that the information was entered in a table format by not approving decisions that did not have the information in a table layout
Outcome - here is where we recorded the decision/option selected
Outcome Reasoning - why we went with the outcome we went with

And we also added custom link types

Impacts/Impacted By - use when linking the decision with delivery work impacted by it
Overrides/Overriden By - this was used to indicate when the project direction as such that we had to pivot on a previous decision; we chose to use this as opposed to editing the existing decision record, as it would make it easier to see on a list as opposed to having to click into each decision ticket

Hope this helps.

Garth Bond

I create a RAID (Risks, Actions, Issues & Decision) database for each Project in Confluence and I track these in this database. When we project reviews I refer to this, filtered by priority.

Devlend Maul

There are a number of factors to consider, but if decisions are scattered across Zoom meetings, Confluence pages, Jira comments, and even other applications like Slack, I would suggest exploring leveraging Rovo and maybe Loom to tie all the sources together so you don't have to play detective.

As long as you build the connective tissue between the information sources such as referencing work item keys, linking Confluence pages, or connecting Rovo to your other applications, Loom and Rovo agents can analyze, structure, and store or provide the information you are looking for regardless of where and when it was documented.

For example, you can add Loom to your Zoom meeting and have it automictically generate a Confluence page of the meeting notes and identify action items and decisions. Then use Rovo Search or a specialized Rovo agent to generate the information you need in the way you need it.

You can have Rovo automictically analyze the content and if important information is missing like "who approved a major scope or design change" have it take action like sending a notification to someone.

There is obviously an investment of time, architectural configuration, and strategy but once you have the tools, processes, and governing frameworks in place, it can scale and save time with little overhead.

dkrie

@Felipe Sozinho & @Lucian Irimie we do something similar.

Originally we had a different Tool, build in Salesforce, when implementing it as a global platform. We had a dedicated record type for it. When transferring to Jira, these were not moved over.

For quite a long time, we thought "we'll manage". But as time passes, people on the move, new colleagues and past decisions being challenged, we identified a need to revive documentation of our decisions.

We have a Design Authority Board and a group of architects, that owns decisions. Meaning, they decide which to create and are responsible of keeping these up to date. For that purpose we have created a dedicated record type in Jira "Decisions". We keep it fairly simple. We have a status, rich text fields, link to impacted user stories/ideas and has fields to document who took the decisions.

Decisions we document are overall and principle decisions, e.g. why a certain app was chosen over another. Or why we did(n't) implement certain features. The description will contain various pro's & con's and documentation for instance concerning license schemes, impact on storage and compatibility with the overall application landscape in company.

It takes some diligence to keep the records maintained, but it's surely worth it! Minor decisions/documentation is kept on user stories, and we lost track of major decisions when they were all cluttered in the user stories. Now it's much cleaner, and it helps facilitate understanding to (new) mgmt., that we can verify the rationale behind current set-up.

Currently I'm in the process of extracting old decisions from our previous tool, decide which are relevant, and merge/update and transfer to Jira. Looking much forward to be done

Welcome!

It looks like you're new here. Sign in or register to get started.

Quick Links

Find more posts tagged with

jira-cloud

jira-administration

best-practices