Keep a Decision Log in Jira: Remember Why You Chose This Approach

Six weeks after a release, someone asks why the team chose email notifications instead of a daily digest. The Jira tickets explain what was built. A comment says “agreed in planning.” The people who remember the discussion are busy, and nobody is sure which constraint mattered most.

A decision log fills that gap. It records the situation, the options, the choice and its consequences in a place the team can find. With Power Pack's Decision Log, that record sits beside a Jira issue, close to the work it explains.

This guide follows a fictional customer portal team as it writes one useful record, connects it to delivery and revisits it when customer needs change.

Decide what deserves a record

A decision log does not need to capture every conversation. Start with choices that future teammates may reasonably question: a delivery approach, a dependency, a release boundary or a deliberate compromise with consequences beyond one small task.

For our portal team, notification delivery qualifies. Choosing immediate email shapes implementation, testing, support instructions and customer expectations. The team has considered alternatives and expects to reconsider the choice if message volume grows.

By contrast, correcting a spelling mistake in a button label probably does not need its own decision record. The distinction is practical: would understanding the reasoning help someone maintain, change or explain the result later?

Architecture decision records, often called ADRs, provide a useful precedent. Michael Nygard's original article describes short records that preserve context, a decision, status and consequences, retaining replaced decisions with a reference to the new choice. The source is linked below. Our example applies that lightweight idea to a Jira delivery decision.

Give the decision a clear home

Choose the Jira issue that best represents the work affected by the choice. For this example, the team uses the issue coordinating customer portal notifications. It already points readers toward the implementation and testing work.

Tell the team where the record lives. Power Pack's Decision Log belongs to an issue, so establish a simple habit for finding it. A note in the coordinating issue can say that notification decisions are maintained there. If your team keeps a separate project index, add the issue there through your normal process.

Avoid spreading copies across several issues and expecting them to stay aligned. Other tickets can refer readers to the chosen home. Exported copies are useful for discussion, but the team should know which record to consult for the current position.

Write the context before the conclusion

Context explains why the question exists. It should distinguish facts, constraints and assumptions so that a future reader can tell which part changed.

The portal team writes: “Customers need to know when a support request meaningfully changes. The current service already sends email. The first portal release does not include an inbox. We expect most requests to have a small number of customer-visible status changes, but we have not yet measured notification volume after launch.”

That paragraph is more useful than “email is the simplest option.” It explains the starting point and makes an assumption visible. It also avoids claiming that email will always be the right channel.

Add references to supporting investigation where appropriate. If a technical spike informed the choice, identify the Jira issue containing its findings. If customer feedback matters, summarize the relevant pattern without copying private information unnecessarily into the decision.

The context should let a new colleague understand the situation without reconstructing an entire meeting. Keep the detail that influences the choice and leave unrelated discussion in its original location.

Compare genuine alternatives

A useful record shows what the team could have done. Include the alternatives that were seriously considered, with an honest advantage and disadvantage for each.

These are illustrative assessments for this fictional system. Another team may already have an inbox or a digest service, changing the comparison completely. Good decision writing makes that dependence on context visible.

Do not weaken rejected options just to make the selected one look inevitable. A digest has a real benefit: fewer separate messages. The team chooses against it for this release because timing and implementation scope matter more under the current assumptions.

Also distinguish an option from a separate decision. Whether to show a customer's full message inside an email may require its own review. Folding every notification question into one entry makes it difficult to understand what was actually agreed.

State the choice and its consequences

Write the decision as a complete sentence: “For the first portal release, we will send an email when a support request has a meaningful customer-visible status change. Internal edits will not trigger a message.”

Then explain why: “This uses the existing delivery channel and gives customers prompt progress updates while keeping the release scope manageable.” The sentence describes the rationale for this example; it does not claim that email is universally cheaper or more reliable.

Consequences deserve equal attention. The team needs a shared definition of a meaningful change. Testing must cover repeated updates and duplicate handling. Support needs to explain which events produce messages. Customers with busy requests may still receive more email than they want.

A useful consequence leads naturally to follow-up work. Record the implication here, then manage the task in Jira. A decision entry should help someone discover why work is necessary without becoming a second backlog with competing statuses and owners.

Create the record in Power Pack

Open Power Pack on the relevant Jira issue and use Decision Log (ADR Lite). Add an entry with a title that names the actual choice, such as “Use immediate email for routine portal status updates.”

Choose a category appropriate to your team's use and start with Proposed while the outcome is still under discussion. Add the decider and, when the choice is made, its decision date. The decider field records who owns the choice; entering a name does not carry out an approval process for you.

Fill in the context, add the alternatives with their pros and cons, select the chosen option and write the consequences. Keep the content understandable to someone who did not attend the discussion.

Add impacted Jira keys where useful. The editor accepts comma-separated issue references, which can identify the implementation and testing tickets affected by the decision. Treat them as recorded references; use Jira's normal linking process separately when you need an issue relationship.

Review the completed entry with the people involved. Check that the selected option and written explanation agree. Confirm the save state before asking teammates to rely on the latest version, particularly if the tool indicates a local or offline state.

Use status to make the current position clear

Power Pack provides Proposed, Accepted, Rejected and Superseded statuses. Agree how your team will use them so that a reader can distinguish an idea awaiting a decision from a choice already guiding delivery.

When Maya, the product owner, makes the notification decision, the team records the date and marks the entry Accepted. That status describes the decision's position. It does not prove that implementation is complete, that tests passed or that the release is authorized.

The same distinction matters for Rejected. If a proposal is not adopted, a short explanation can save the next person from repeating an investigation without knowing it already happened. Preserve useful reasoning even when no delivery ticket follows.

Revisit a decision when its assumptions change

After launch, imagine the portal expands to include customers with many active requests. Support reports that some receive several routine emails each day. That is new context, directly related to the original assumption about low message volume.

The team opens the old record before proposing a change. It can now separate an earlier reasonable tradeoff from the question facing the product today. The existing decision explains why immediate email was chosen; it does not forbid a better approach under different conditions.

Create a new Proposed entry for a daily digest option. Power Pack supports duplicating an entry into a Proposed record, which can provide a starting point. Review every copied field carefully: old assumptions, dates and consequences may no longer apply.

When the new choice is accepted, mark the earlier record Superseded and reference the replacement decision in its replacement field. Keep the original reasoning readable rather than rewriting it as though the team had always intended a digest.

This is a team documentation practice. The records remain editable, so agree to create replacement entries for substantive changes and reserve ordinary edits for corrections or clarification. Do not treat the log as an immutable audit trail.

Make the record useful during everyday work

Use the log when someone joins the team, proposes a redesign or asks why a ticket includes an unusual requirement. Search and filtering can help locate an entry within the issue's log. Power Pack can also export ADR-style Markdown for a review or another documentation workflow.

Before sharing an export, check that it reflects the current entry and identify the issue where the team maintains the record. A downloaded document is a snapshot; future edits to the issue will not update a copy already sent elsewhere.

Start with one decision your team has recently made and is likely to revisit. Write the context, the real alternatives, the chosen approach and the consequences. Put that record beside the Jira work in Power Pack, then ask a teammate who missed the discussion to read it. If they can explain why the choice made sense and what would justify changing it, the log is doing useful work.

• Michael Nygard: Documenting Architecture Decisions