Topic: ADR template for Jira

ADR Template for Jira — Custom Fields, Confluence Integration, and the Graduated Handoff

Q: Can Jira Issues replace git-based ADRs long-term?

No — for two structural reasons. First, ADRs derive their authority from being immutable once Accepted: a Markdown file committed to git cannot be silently edited without a commit trail. Jira Issue descriptions can be edited by any project member with write access and the edit history is surfaced only via the Issue's change log, not as a first-class audit trail that blocks mutation. Second, ADRs need to outlive your project management tooling. Teams that kept architecture decisions exclusively in Jira have lost them during Jira Cloud migrations, project key renames, project archival, and company acquisitions that changed the Atlassian subscription. Markdown files in a code repository survive all of those events. Use Jira Issues to track the ADR lifecycle (Status, Decider, triggering links) and as the short-term drafting container, then graduate each Accepted ADR to a committed Markdown file. The Jira Issue becomes the provenance record; the Markdown file is the canonical ADR.

Q: What custom fields are most useful for Jira ADR tracking?

The four most useful custom fields for a Jira ADR Issue type are: ADR Status (select field with values Proposed / Under Review / Accepted / Superseded / Deprecated — distinct from the Jira workflow status so it does not disrupt the standard Done/In Progress pipeline), Decider (user picker, single select — the engineer who made the final call, not the Issue reporter), Date Decided (date picker — when the decision was formalized, not when the Issue was created), and Supersedes (text field — the Jira Issue key of the ADR this one replaces, e.g., MYPROJ-042). A fifth field, Repo File (URL field), is added at graduation time and points to the committed Markdown file in GitHub or GitLab. Do not add more than five fields at the start — schema inflation makes the Issue type feel bureaucratic and engineers stop filling in the metadata consistently.

Q: Does the Jira data export include full ADR body text?

Partially. Jira's built-in CSV export (Issues → Export → CSV) includes the Issue summary, description, custom fields, and standard fields. The description field (which holds the ADR body text) is exported as plain text with most formatting stripped — no code block syntax, no table markup, no heading hierarchy. The Jira REST API (/rest/api/3/issue/{issueKey}) returns the description in Atlassian Document Format (ADF), a JSON-based structured format that preserves formatting but requires conversion to Markdown. For Confluence pages, the Confluence Space export (HTML or PDF) includes full page bodies with formatting intact, but in HTML not Markdown — a closer-to-Markdown conversion is possible with HTML-to-Markdown tooling but it is not lossless. This export gap is the structural argument for the graduated handoff: Markdown files in git are already in the right format and survive any Atlassian subscription change, while Jira/Confluence exports require conversion and manual review to recover the same content.

Most enterprise engineering teams already live in Jira. The natural instinct is to put architecture decision records where the work lives — alongside the Epics they govern, visible in the same project board, searchable in the same tool. This page explains two Jira-native ADR patterns (Issue-as-container for small teams, Confluence-page-as-body for larger teams), the custom fields that make ADR tracking useful, and the graduated handoff to committed Markdown that gives ADRs the immutability guarantee they need to be authoritative long-term.

TL;DR

For small teams (ten or fewer engineers): create a custom Jira Issue Type called Architecture Decision, add four custom fields (ADR Status, Decider, Date Decided, Supersedes), and use the Issue description as the ADR body in Nygard format. For larger teams: create Confluence pages as ADR bodies linked bi-directionally to Jira Epics via the Jira Links macro. In both cases, graduate each Accepted ADR to a committed Markdown file in /doc/decisions/ — the Jira Issue becomes the provenance record, the Markdown file is the canonical ADR. Neither Jira Issues nor Confluence pages provide the immutability guarantee that ADRs require; only a git commit trail does.

Why engineers want ADRs in Jira

Jira is the primary work-tracking tool for most engineering teams at companies with five or more engineers. Decisions and the implementation work they govern live in the same project: the Epic to migrate from REST to GraphQL is in Jira, the Stories scoped under that Epic are in Jira, and the engineers who need to understand the architecture rationale are spending most of their day in Jira. The instinct to put the ADR in the same place is reasonable. There are three genuine advantages to a Jira-native ADR approach:

Proximity to implementation work. An ADR linked to the triggering Epic is one click away when engineers plan a sprint. They do not need to navigate a git repository or remember a filename convention to find the rationale for a system choice. The decision is surfaced at the point of use.
Lifecycle tracking in familiar tooling. Jira's custom fields and workflow statuses let teams track ADR status (Proposed → Under Review → Accepted → Superseded) using the same tooling they use for story lifecycle. Engineering managers who are comfortable in Jira dashboards can build ADR status reports without learning a new tool.
Issue linking for traceability. Jira's native Issue Links feature (the "documents" / "is documented by" link types) creates explicit bidirectional links between an ADR Issue and the bugs, features, or Epics it governs. When a future engineer opens a linked Issue, the ADR is surfaced automatically — no cross-referencing or search required.

There are also three structural limitations that prevent a pure Jira approach from working as the canonical ADR archive:

No immutability guarantee. Jira Issue descriptions can be edited by any project member with write permission. The change log records edits, but it does not prevent silent modification of a decision body after it has been Accepted. ADRs derive their authority from being unchangeable once finalized — the only mechanism that enforces this reliably is a git commit trail on a file in the repository.
No document-grade formatting for the body. Jira's Issue description field uses Atlassian Document Format (ADF) internally. While the Jira editor renders headings, code blocks, and tables visually, the underlying representation is not Markdown. This matters at export and migration time: Jira's CSV export strips most formatting from the description field, and ADF-to-Markdown conversion is lossy for tables and inline code.
Jira's export covers Issues, not document bodies at full fidelity. Jira's built-in CSV export is designed for sprint reporting and project analytics — it includes summaries, statuses, and custom fields, but the description body is flattened to plain text. Recovering the full ADR content from a Jira export requires the REST API and ADF-to-Markdown conversion. Teams that discover this during a tool migration often find partial content loss.

Two approaches: Jira Issue vs Confluence page

The right approach depends on team size and how much your organization is already invested in Confluence:

Small teams (ten or fewer): Jira Issue as ADR container

For a team of two to ten engineers, the simplest Jira ADR setup is a dedicated Issue Type with the ADR body in the description. There is no additional tool to configure, no Confluence space to maintain, and no context-switch between the drafting environment and the work-tracking environment. Engineers create a new Architecture Decision Issue, write the Nygard-format body in the description, fill in the four custom fields, and link the Issue to the triggering Epic or Story. The Issue description is mutable by design during the draft phase — engineers iterate on the Consequences section, the Decider requests changes to the Alternatives table, the lead engineer finalizes the Decision sentence. When the team reaches consensus, they update the ADR Status custom field to Accepted, and the graduated handoff begins.

The limitation is real but manageable: the Issue description has no immutability constraint. Once the ADR is Accepted, the graduated handoff resolves this by making the committed Markdown file the canonical source. The Jira Issue description becomes the drafting artifact, not the permanent record.

Mid-size teams (ten or more): Confluence page linked from Jira Epic

For teams of ten or more engineers using Confluence, the standard Atlassian-stack approach separates the ADR body from the ADR metadata. The Jira Epic (or an Architecture Decision Issue) holds the custom fields — ADR Status, Decider, Date Decided, Supersedes — and the Jira-side links to triggering Issues. The Confluence page holds the ADR body: the full Nygard-format document with proper heading hierarchy, formatted code blocks, decision tables, and a comment thread for deliberation on specific paragraphs.

The Confluence page is linked to the Jira Epic via two mechanisms: the Jira Links macro embedded in the Confluence page (which renders the live Jira Issue details inline), and a "Confluence page" remote link on the Jira Epic (accessible via the Issue's Web Links panel). This bidirectional link means engineers in Jira can navigate to the Confluence ADR body, and engineers in Confluence can navigate to the implementation Epic.

Both approaches require the graduated handoff to committed Markdown for the canonical archive. Neither Jira Issues nor Confluence pages are the right long-term home for ADRs.

Option 1: Jira Issue as ADR container

The minimal setup for Jira-native ADR tracking requires configuring a new Issue Type and four custom fields in your Jira project.

Creating the Architecture Decision Issue Type

In Jira: go to Project Settings → Issue Types → Add Issue Type.
Name it Architecture Decision. Use a description like "An immutable record of a significant technical or architectural choice and its rationale." Set the icon to something visually distinct from Story and Epic (the diamond icon works well).
Add the Issue Type to your project's Issue Type Scheme so it is available when creating Issues.

Required custom fields

Field name	Type	Values / notes	When to populate
ADR Status	Select (single)	Proposed / Under Review / Accepted / Superseded / Deprecated	At creation (Proposed). Distinct from Jira workflow status — do not use Done to mean Accepted.
Decider	User picker (single)	The engineer or EM who made the final call — not the Issue reporter	When Status moves to Under Review. Prevents "who owns this?" during oncall handoff.
Date Decided	Date picker	When Status moved to Accepted — not when the Issue was created	At graduation. Gap between created and decided reveals how long decisions take to finalize.
Supersedes	Text (short)	Jira Issue key of the ADR this one replaces (e.g., "MYPROJ-042")	Only when this ADR replaces a prior decision. Keep as text — the CI check on the Markdown file enforces the actual file pointer.
Repo File	URL	Direct link to the committed Markdown ADR file in GitHub or GitLab	Added at graduation. Turns the Jira Issue into a pointer to the canonical file.

ADR body text in the Issue description

The Issue description holds the full Nygard-format ADR body. Use this structure, which matches the Nygard template and converts cleanly to Markdown at graduation:

h1. ADR-NNN: [Title — name the decision, not the problem]

h2. Status
Proposed

h2. Context
[Two to four sentences. What situation forced this decision? What constraints exist?
What would happen if we made no change? Do not include the decision itself here.]

h2. Decision
[One active-voice sentence: "We will use X." Not "X was chosen" or "We should consider X."]

h2. Consequences
[Bulleted list. At least one genuine downside — an ADR with only positive consequences is a press release.]

Positive:
* [something that improves]

Negative (trade-offs):
* [something that gets worse or becomes harder]

Neutral:
* [something that changes but is neither better nor worse]

h2. Alternatives considered
[For each rejected alternative, one sentence on why. Prevents re-litigating closed decisions.]

|| Option || Why rejected ||
| [Option A] | [one-sentence rejection rationale] |

h2. Stakeholders
[Who was consulted before this decision? Relevant for decisions that cross team boundaries.]

h2. Deliberation record
[Link to the Issue or discussion thread that triggered this decision. Link to Chat export if applicable.]

Issue linking

Use Jira's native Issue Links to create explicit relationships between the ADR Issue and the work it governs. The most useful link types for ADRs are:

"documents" / "is documented by" — link the ADR Issue to the Epic or Story that triggered the architecture decision. The triggering Issue is now one click away from the rationale.
"is superseded by" / "supersedes" — if this ADR replaces an earlier one, link them directly. This creates a navigable supersession chain inside Jira independent of the Supersedes custom field text.
"relates to" — for Issues that are affected by the decision but did not trigger it. Use sparingly — linking an ADR to every affected Issue collapses the signal-to-noise ratio.

Title ADR Issues using the convention ADR-NNN: [Name the decision, not the problem] — for example, ADR-042: Use PostgreSQL full-text search instead of Elasticsearch. This makes ADR Issues scannable in the Backlog view and searchable by number in comments across the entire project.

Option 2: Confluence page as ADR body

For teams already using Confluence alongside Jira, the recommended approach is to store the ADR body in a Confluence page and the ADR metadata (Status, Decider, Date Decided) in a Jira Issue. This is the standard Atlassian stack approach and gives you proper document-grade formatting, paragraph-level comment threads for deliberation, and a more complete export path.

Setting up the Confluence Architecture Decisions space

In Confluence: navigate to your Engineering space and create a page tree called Architecture Decisions as a top-level child of the space root. Do not use a project-scoped space — ADRs outlive any single project.
Create a child page called Index that lists all ADRs by number with their status. This becomes the navigable ADR register without needing a separate tool.
Create a Confluence Blueprint or Page Template called Architecture Decision Record with the Nygard sections pre-filled. Templates appear in the Create dialog and enforce consistent structure without requiring engineers to remember the format.

Using Confluence macros for ADR structure

Confluence macros add structural metadata that plain Markdown cannot — particularly useful for the Status and Jira link fields visible at the top of each ADR page:

Status macro — place at the top of the page body next to the ADR title. Configured with colour coding: grey for Proposed, yellow for Under Review, green for Accepted, red for Superseded. This gives reviewers instant status visibility without reading the full document.
Info macro — wrap the Decision section in an Info macro (blue background). This visually separates the decision sentence from the surrounding rationale and makes it impossible to miss in a quick scan.
Jira Issues macro — embed the triggering Jira Epic directly in the ADR page. The macro renders live Issue status, assignee, and summary inline in the Confluence page. Engineers reviewing the ADR see the implementation Epic without leaving Confluence.
Table of Contents macro — add at the top of the page body for ADRs with long Consequences and Alternatives sections. Allows navigating directly to the Decision sentence.

The Confluence ADR page template structure

[Status macro: Proposed / Under Review / Accepted / Superseded]

[Jira Issues macro: {jira:key=MYPROJ-NNN} — the triggering Epic]

h2. Context

[Two to four sentences describing the situation that forced this decision.
Constraints, background, what changes if no decision is made.
Do not include the decision itself in this section.]

h2. Decision

[Info macro — blue background]
We will [one active-voice sentence naming the chosen option].
[/Info macro]

h2. Consequences

*Positive*
* [something that improves]

*Negative (trade-offs)*
* [something that gets worse or becomes harder]

*Neutral*
* [something that changes but is neither better nor worse]

h2. Alternatives considered

|| Option || Why rejected ||
| [Option A] | [one-sentence rejection rationale] |
| [Option B] | [one-sentence rejection rationale] |

h2. Stakeholders

[Who was consulted before this decision? Names or team names, not roles.]

h2. Deliberation record

[Links to the Jira Issue that triggered this ADR, any relevant Slack threads,
and AI chat export links (see WhyChose extractor for recovering AI session reasoning).]

h2. Graduated file

[Added at graduation time: link to the committed Markdown file in the repository.]

Atlassian Marketplace plugins for ADR workflows

The Atlassian Marketplace has several plugins that extend Jira and Confluence specifically for ADR workflows:

Architecture Decision Records by Communardo — a Confluence plugin that provides an ADR Blueprint (page template with Nygard sections and Status macro pre-configured), an ADR index page that auto-populates from child pages, and a Jira panel on Issue detail views that surfaces linked Confluence ADRs. Available on the Atlassian Marketplace for Confluence Cloud and Data Center.
Structure by ALM Works — a Jira plugin for hierarchical Issue views. Useful for creating an ADR hierarchy view that groups Architecture Decision Issues by domain or by the Epics they govern. Not ADR-specific, but commonly used by teams with large ADR backlogs that need more than the default Backlog view.
ADR Blueprint plugins — several community-maintained Confluence Blueprint plugins on the Marketplace create the page template, index page, and Status macro configuration automatically. These reduce the setup time from 30 minutes of manual configuration to under five minutes.

Even with plugins, the export gap remains: plugin-created Confluence pages export via the standard Confluence Space export (HTML/PDF/XML), not native Markdown. The graduated handoff to committed Markdown is still required for immutable long-term archival.

The Jira and Confluence export gap

Understanding what Jira and Confluence do and do not export determines how much migration risk you carry if your ADRs live only in the Atlassian stack:

Item	In Jira CSV export?	In Confluence Space export?	Via API?	Notes
Jira Issue title (ADR-NNN summary)	Yes	n/a	Yes	Fully preserved in CSV and REST API `/rest/api/3/issue/{key}`.
Jira custom fields (ADR Status, Decider, Date Decided)	Yes	n/a	Yes	All custom fields in CSV export and REST API. Field IDs needed for API queries.
Jira Issue description (ADR body text)	Yes — as plain text, formatting stripped	n/a	Yes — as ADF JSON	CSV export flattens tables and code blocks to plain text. ADF JSON requires conversion to Markdown.
Jira Issue links (documents / is documented by)	Partially — link type and linked key only	n/a	Yes — via `issuelinks` field in REST API	The relational graph of ADR-to-Epic links is only fully queryable via the REST API.
Confluence page body	n/a	Yes — HTML or PDF	Yes — Confluence REST API as storage format HTML	HTML export preserves formatting but is not native Markdown. Requires HTML-to-Markdown conversion with manual review.
Confluence page comments	n/a	Yes — included in Space export	Yes — via Confluence REST API	Deliberation comments on specific paragraphs are the most valuable historical context — preserved in Space export backup.
Jira-Confluence bidirectional links	Partially — remote links in Issue API	n/a	Yes — Issue remote links and Confluence page metadata	The full relational graph (ADR Issue ↔ Confluence page ↔ triggering Epic) is only reconstructible via combined API queries.

Confluence's Space export (HTML/PDF/XML) is a meaningfully better export story than Linear's API-only path for Documents — the page bodies are included in the export archive. But it is still not native Markdown: converting a Confluence HTML export to well-formed Markdown requires tooling and manual review, particularly for pages that use Jira macro embeds and Info/Status macros. The graduated handoff pattern resolves this by making the Markdown file the primary artifact and treating the Confluence page as a transient drafting surface.

The graduated handoff: from Jira or Confluence to committed Markdown

The graduated handoff has three phases, with Jira-specific steps at each stage:

Draft in Jira or Confluence. Create the Architecture Decision Issue (small teams) or the Confluence page (larger teams). Engineers iterate collaboratively — the Decider requests changes to the Alternatives section, others push back on Consequences, the lead engineer finalizes the Decision sentence. The ADR Status custom field is set to Proposed or Under Review. The content is mutable and expected to change.
Accept and graduate. When the team reaches consensus:
- Update the Jira ADR Issue's ADR Status custom field to Accepted.
- Copy the Confluence page body (or Jira Issue description) to a Markdown file using the Nygard filename convention: NNNN-title-in-kebab-case.md. For example: 0042-use-postgresql-full-text-search.md.
- Include the Jira Issue key and the Confluence page URL in the ADR's Deliberation record section: "Triggering Epic: MYPROJ-038. ADR review thread: [Confluence page URL]." This link is preserved in the committed file even after Jira and Confluence are replaced.
- Commit the Markdown file to /doc/decisions/ via a pull request. The PR description links back to the Jira Issue key — this creates a GitHub-to-Jira reference visible in both tools.
- Merge the PR after the ADR review checklist passes.
Archive the Jira and Confluence sources.
- Update the Jira ADR Issue's Repo File custom field with the direct URL to the committed Markdown file in GitHub or GitLab.
- Add a comment to the Jira Issue: "This ADR has graduated to [link to Markdown file in repository]. The Issue description is a deliberation artifact. The canonical ADR is the committed Markdown file."
- If using Confluence: update the Confluence page to show a notice at the top using an Info macro: "This page has graduated to [ADR-042 in the repository]. This page is a deliberation record — it is not the canonical ADR. Do not edit the decision body." Update the Confluence page's Status macro from Accepted to a custom "Graduated" status if your template supports it.
- Transition the Jira Issue to the Done workflow status (or a custom "Graduated" status if your team's Jira workflow includes one). The ADR metadata lives in the custom fields indefinitely; the workflow status signals that no further action is required.

The graduated Markdown file is the canonical ADR. It is subject to the ADR review checklist, the immutability guarantee that every git commit enforces, and the CI validation that runs on every PR to the /doc/decisions/ directory. The Jira Issue and Confluence page are preserved as provenance records — useful for future engineers who want to understand the deliberation, not just the decision.

Jira and Confluence vs other PM tools for ADR storage

Tool	Best use in ADR lifecycle	Immutability guarantee	Export path	Cross-links to Issues?
Jira Issues	ADR metadata tracking and Issue linking (small teams: also the drafting container)	None — description editable by any project member; change log tracks edits but does not prevent them	CSV export (description as plain text); REST API as ADF JSON	Yes — native Issue Links with typed link relationships
Confluence pages	ADR body drafting and stakeholder review (mid-size and enterprise teams)	None — page versioning exists but no immutability constraint; any editor can overwrite the accepted body	Space export HTML/PDF; Confluence REST API as storage-format HTML	Yes — Jira Issues macro embeds live Issue data in the page
Linear Documents	Drafting and review for teams using Linear for project management	None — editable by anyone with workspace access	GraphQL API only (body not Markdown); no CSV or file export for Documents	Yes — native Relations feature links Documents to Issues and Projects
Notion	Drafting and stakeholder review; Notion database as ADR register	None — full edit history but no immutability constraint	Markdown export available per page; closest to native Markdown of the PM tools	Via Relation property between ADR database and Issues database; or via mentions
Obsidian	Personal PKM drafting; Dataview queries for personal ADR status dashboards	Via git sync (optional, but most Obsidian-for-ADR setups use git-backed vaults)	Native Markdown — files are already in the right format	Via wikilinks to Issue URLs in note body or YAML frontmatter
Git repo (Markdown files)	Canonical archive — the immutable source of truth after graduation	Full — every edit is a commit with author, timestamp, and diff; cannot be silently modified	Native — files are already Markdown, readable by every editor	Via URL link in ADR text body and PR description back to Jira Issue

Why this matters for decision capture

The Jira-native ADR pattern — whether using Jira Issues or Confluence pages — solves the drafting-vs-archive problem: decisions are created close to the implementation work they govern and graduated to an immutable archive once finalized. But it does not solve the upstream gap: decisions that were made in AI chat sessions before any Jira Issue or Confluence page existed.

In practice, the reasoning behind significant architecture decisions often happens in ChatGPT or Claude before anyone writes a Jira Issue. An engineer asks an AI assistant to compare database options, works through the trade-offs across several turns, reaches a conclusion — and then creates a Jira Epic for the migration without ever writing down the rationale that led to the choice. Six months later, a new team member opens the Epic and sees what was built, but not why. The deliberation that justified the choice is in an AI chat history that may not even be accessible anymore.

For decisions already captured in AI chat history, the WhyChose extractor reads your ChatGPT or Claude export and surfaces the architecture calls inside as structured decision records — formatted in Nygard-compatible Markdown, ready to drop into the /doc/decisions/ directory or paste into a Jira Issue description or Confluence page. The extracted records include Context, Decision, and Consequences sections reconstructed from the conversation, giving you a starting point for the review cycle that the original chat session skipped. Paste the extracted ADR into a new Confluence page, tag the Decider, set the Jira ADR Status to Under Review, and trigger the graduated handoff from there.

Get early access