ADR Template in Obsidian — Dataview Queries, Auto-Numbering, and the Supersession Canvas

Vault layout

The ADR folder should sit inside your existing engineering vault, not in a separate vault. A standalone ADR vault isolates your decision records from the research notes, spike results, and meeting notes that inform them — you lose the ability to link an ADR to the ChatGPT conversation that shaped its Context section, or to the RFC document that preceded the decision. Inside the vault, use a flat folder:

vault-root/
├── decisions/
│   ├── _template.md          ← ADR scaffold (not numbered)
│   ├── 0001-choose-postgres.md
│   ├── 0002-use-redis-for-queue.md
│   ├── 0003-adopt-graphql-api.md
│   └── ...
├── research/
├── meetings/
└── ...

Keep the ADRs flat (one level, no subdirectories within decisions/) for single-service repositories. If you work across multiple services, use a subdirectory per service:

decisions/
├── api-service/
│   ├── 0001-choose-postgres.md
│   └── ...
├── infra/
│   ├── 0001-use-terraform.md
│   └── ...

Dataview queries can be scoped to a path (FROM "decisions/api-service"), so the per-service dashboard is one query argument away. The GitHub Action CI should be configured to lint each subdirectory independently with its own numbering sequence.

One file to keep in version control that does not need to be: the Obsidian configuration folder .obsidian/. Add it to .gitignore. It contains theme preferences, plugin cache, workspace layout, and settings that differ per machine and have no value in code review. Commit only the ADR Markdown files and the template scaffold.

YAML frontmatter schema for Dataview

The Obsidian Dataview community plugin queries vault files via their YAML frontmatter. Without frontmatter, Dataview can still list files, but it cannot filter by status, sort by date, or show which ADRs are in the supersession chain for a given decision. The investment in a consistent frontmatter schema pays off the first time you want to answer "which ADRs are currently in Accepted status?" without reading every file.

The minimal Dataview-compatible ADR frontmatter block:

---
title: "Use Postgres as the primary relational database for the user service"
status: Accepted
date: 2026-03-15
deciders: [alice, bob]
supersedes: ""
superseded-by: ""
tags: [database, infrastructure]
---

Field notes:

• status — Use exactly these values: Proposed, Accepted, Superseded, Deprecated, Rejected. Avoid variants like Draft, WIP, or Active — the ADR status template documents why variant explosion is the most common consistency failure in ADR directories. The GitHub Action CI lints for exactly these values, so frontmatter and CI need to agree.
• date — ISO 8601 (YYYY-MM-DD). Dataview's date() function parses this natively, so date-range queries work without string coercion.
• deciders — Array of names or initials. This is a routing field for questions, not a blame field. Keep it short enough that it survives personnel changes without becoming a stale list.
• supersedes — Filename of the ADR this one replaces (e.g. 0031-use-mysql.md). Leave empty string "" when not applicable. Dataview can query WHERE supersedes != "" to find the supersession chain.
• superseded-by — Filename of the ADR that replaced this one. Filled only when the ADR's status changes to Superseded. The supersession pattern requires both files in the same PR — this frontmatter field is the Obsidian-visible half of the bidirectional pointer.
• tags — Keep under 15 distinct values across the whole directory. Tags work best for broad domain labels (database, infrastructure, api, security) that make the Dataview filter query short, not for fine-grained categorization.

Scaffolding new ADRs: core Templates vs Templater

Obsidian ships with a built-in Templates plugin (Settings → Core plugins → Templates). It inserts the content of a template file at the cursor, with optional {{date}} and {{title}} substitutions. This covers the structure — you get the standard headings pre-populated — but it does not auto-number the file. You still have to rename the file to the next sequential number manually.

The core Templates approach is viable for teams writing one or two ADRs per month — the manual rename takes five seconds and the plugin has zero maintenance surface. Create decisions/_template.md:

---
title: "{{title}}"
status: Proposed
date: {{date:YYYY-MM-DD}}
deciders: []
supersedes: ""
superseded-by: ""
tags: []
---

## Context
[What is the situation that makes this decision necessary? Two to four sentences.
State the problem, the constraints, and what made this decision non-obvious.]

## Decision
[One sentence. "We will use X for Y." Active voice. Name what was chosen, not why.]

## Consequences
- Makes harder: [one thing that becomes more difficult]
- Makes easier: [one thing that becomes simpler]
- Trade-off accepted: [the downside you consciously accepted]

For teams writing ADRs frequently enough that numbering collisions are a real risk — two people writing ADRs on parallel branches at the same time — the community Templater plugin (by SilentVoid13) adds JavaScript-level template variables that can compute the next ADR number from the files already in the folder. A Templater template that auto-numbers:

<%*
// Count existing ADR files in the decisions/ folder to find the next number.
// Templater runs this at file creation time inside the vault.
const folder = app.vault.getAbstractFileByPath("decisions");
const files = folder ? folder.children.filter(f => f.extension === "md" && !f.name.startsWith("_")) : [];
const nextNum = String(files.length + 1).padStart(4, "0");
const title = await tp.system.prompt("ADR title (decision statement, not the problem)");
const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
await tp.file.rename(`${nextNum}-${slug}`);
tR += `---\ntitle: "${title}"\nstatus: Proposed\ndate: ${tp.date.now("YYYY-MM-DD")}\ndeciders: []\nsupersedes: ""\nsuperseded-by: ""\ntags: []\n---\n\n## Context\n\n\n## Decision\n\n\n## Consequences\n- Makes harder: \n- Makes easier: \n`;
%>

One caution on auto-numbering in Obsidian: the Templater count-based approach can produce collisions if two team members create an ADR simultaneously on separate machines before Sync reconciles, because both will count the same number of existing files. The GitHub Action CI catches this collision on the PR — two PRs both proposing ADR-0043 will fail the merge-base check. Treat the Templater number as a draft proposal; the CI number is authoritative.

Three essential Dataview queries

Install the Dataview community plugin (Settings → Community plugins → Browse → search "Dataview" → Install → Enable). These three queries cover the everyday ADR workflow in Obsidian.

Query 1: Status dashboard — A table of all ADRs grouped by status, sorted newest first within each group:

```dataview
TABLE status, date, deciders, file.link AS "Decision"
FROM "decisions"
WHERE !contains(file.name, "_template")
SORT status ASC, date DESC
```

Paste this into your decisions/README.md or into a dedicated decisions/DASHBOARD.md note. The result is a live-updating table every time you open the note — equivalent to what adr-tools generates with adr list, but with status filtering and clickable links.

Query 2: Recently accepted (last 90 days) — What decisions were made in the last quarter? Useful for the quarterly ADR health review:

```dataview
LIST date + " — " + title
FROM "decisions"
WHERE status = "Accepted" AND date >= date(today) - dur(90 days)
SORT date DESC
```

Query 3: Supersession chain — Which ADRs are currently superseded, and what replaced them? Use this to audit whether all Superseded ADRs have a bidirectional pointer to their replacement:

```dataview
TABLE supersedes, superseded-by, file.link AS "ADR"
FROM "decisions"
WHERE status = "Superseded" OR supersedes != ""
SORT date DESC
```

Any row in this table where superseded-by is empty but status = "Superseded" is a one-sided supersession — the old ADR knows it was replaced but it doesn't say by what. That is the integrity bug the GitHub Action CI catches at merge time; the Dataview query catches it locally before the PR is opened.

Wikilinks vs Markdown links: the portability problem

Obsidian defaults to creating links as [[wikilinks]] when you type [[ or paste a link. Wikilinks are convenient in the Obsidian UI — they resolve by filename without a path — but they are not standard Markdown. External tools that read the ADR files — adr-tools, the GitHub Action CI, Log4Brains, raw GitHub rendering — treat [[wikilinks]] as literal text, not links. The Supersedes and Superseded-by fields that the CI integrity job verifies use grep for patterns like Superseded-by: [text](path.md), not Superseded-by: [[filename]].

The fix is one Obsidian setting: Settings → Files & Links → Use [[Wikilinks]] → off. With wikilinks disabled, Obsidian writes standard Markdown links when you create a link via the normal UI ([[ completion still works but inserts [Display text](path/to/file.md) instead). Existing wikilinks in ADR files are not converted automatically — if you are adopting Obsidian on an existing ADR directory, run a one-time sed pass to convert them, or use the community "Wikilinks to MDLinks" plugin (Search: "wikilinks mdlinks").

For the frontmatter fields supersedes and superseded-by, use bare filenames (0031-use-mysql.md) rather than links. The CI integrity job resolves these by exact filename match; Obsidian's Dataview resolves them as strings for the supersession-chain query. Both tools get what they need from the same value.

Canvas for the supersession graph

Obsidian Canvas (built-in, no plugin required) is a freeform whiteboard where you can embed vault notes as cards. The most useful application for ADRs is a supersession graph for a specific architectural domain: place the active ADRs as cards, the superseded ones as faded cards, and draw arrows for supersession relationships. Annotate arrows with the date the supersession happened.

Create a canvas: New file → New canvas → Save as decisions/supersession-graph.canvas. Drag ADR notes from the vault file explorer onto the canvas. Draw edges by hovering a card until the edge handle appears. Label edges by right-clicking → Edit edge → type the supersession date.

The canvas is a manual artifact — it does not auto-update when you add a new ADR or change a status. The right moment to update it is during the quarterly ADR health review (the same session where you deprecate stale ADRs per the retirement protocol). The canvas is most valuable as a stakeholder communication tool — an architecture board meeting where you need to explain why the team is on its fourth database in three years benefits from a visual timeline of those decisions and their relationships more than from a Dataview table.

The automatic graph view (Ctrl+G) shows supersession relationships as edges only if the ADR body contains inline Markdown links to the related files. Frontmatter field strings are not shown as edges. This is why the supersession-chain query (Dataview) and the inline link in the body (graph view) serve different purposes — use both.

Obsidian Publish vs Log4Brains for non-engineer access

When non-engineers — product managers, executives, new-hire onboarding flows — need to browse ADRs without navigating GitHub, two options exist: Obsidian Publish (the official hosted publishing service, $8/month per vault, zero setup) and Log4Brains (free, open-source, Node.js, self-hosted on GitHub Pages or a static host).

The choice depends on one question: does your non-engineer audience already have an Obsidian account and access to this vault? If yes, Obsidian Publish is worth $8/month because it mirrors the vault they already know. If no, the $8/month is buying them an interface they have never seen, and Log4Brains generates a purpose-built ADR browser that any stakeholder can use without installing anything. The Log4Brains setup guide covers the full deploy-to-GitHub-Pages workflow.

The decisions your Obsidian vault doesn't contain

An Obsidian-based ADR practice is excellent at organizing the decisions your team wrote down. The harder problem is the decisions your team made in AI chat sessions — the two-hour ChatGPT conversation where the senior engineer worked through the Redis vs Kafka trade-offs for the new event bus, reached a conclusion, and closed the tab without writing the ADR. The reasoning existed; it just never made it to a 0042-use-redis-for-event-bus.md file in the decisions folder.

These informal decisions are the most valuable retrospective ADR source because they preserve the trade-off reasoning, the alternatives considered, and the constraint context — exactly the fields that are hardest to reconstruct from memory six months later. The WhyChose extractor reads your ChatGPT or Claude export and surfaces those decisions as structured records in Decision / Context / Consequences format. Import the output directly into your decisions/ folder — it's Markdown, so it drops into the vault without conversion. Dataview queries on the imported records work exactly like queries on the hand-written ones.

Get early access to WhyChose

Related questions

Further reading

• ADR template in Markdown — copy-paste ready — the base Markdown format that Obsidian ADRs use, with the standard five sections and the field notes that explain which parts can be shortened for fast-moving teams.
• ADR storage format comparison — Markdown vs AsciiDoc vs Notion vs Confluence vs SharePoint — when Obsidian's local-first Markdown approach is the right choice vs when a shared wiki wins; the decision matrix includes Obsidian as a storage layer option alongside the standard list.
• ADR tooling comparison — adr-tools vs Log4Brains vs adr-log vs hand-rolled — how Obsidian + Templater fits into the broader tooling landscape; the creation-vs-publication distinction explains why Obsidian handles creation well but still needs Log4Brains or Obsidian Publish for the non-engineer audience.
• Log4Brains ADR — generate an architecture decision record website from your codebase — the full setup guide for the Log4Brains publishing layer that complements the Obsidian-based workflow for teams where not everyone has vault access.
• The ADR supersession pattern — the two-file atomic protocol for supersession that the frontmatter supersedes and superseded-by fields track; the bidirectional pointer integrity check that the GitHub Action CI enforces.
• ADR status template — format, fields, and the lifecycle beyond Accepted — the status field values, what each means operationally, and why variant explosion (using 'Active' instead of 'Accepted', 'Archived' instead of 'Deprecated') breaks Dataview filter queries that depend on exact string matching.
• ISO 25010 quality attributes in ADRs — tagging decisions for architecture governance — extends the Obsidian ADR workflow with a quality-attributes YAML frontmatter field using ISO/IEC 25010 characteristic names (security, reliability, maintainability, performance-efficiency, compatibility, flexibility). Includes the three essential Dataview queries for quality-attribute dashboards, CI enforcement to prevent tag proliferation, and integration with TOGAF and arc42 governance processes.
• The open-source extractor — fills the decisions folder with records recovered from AI chat exports, in Markdown format compatible with the Obsidian vault layout and Dataview schema above.