Skip to content

ADR

Used in the playbook Project foundation, stage 6.

Download adr.md — the source, as in the repository.

How to use

The template's own instructions:

Template from the UASK Engineering Hub, version 2, based on MADR 4 (https://adr.github.io/madr/) and item arch.adr 2.0.0. Save as project/decisions/NNNN-short-title.md (next free number, never reused). Rules: item arch.adr; when it is written: playbook mgmt.project-foundation, stage 6. The earlier version is templates/adr-v1.md; a record without `template:` is checked against it, and a closed one (accepted, superseded, deprecated, rejected) is history and stays as it is. Sections marked "Optional" may be deleted; delete these comments when the record is written.

Fields

Front-matter fields and sections of the document the template creates. A section marked Optional in the template may be deleted from a copy; every other field and section stays (tools/check_artifacts.py checks this for the kinds it knows).

Field or sectionWhereRequired
templatefront matterrequired
idfront matterrequired
titlefront matterrequired
statusfront matterrequired
datefront matterrequired
decision-makersfront matterrequired
owner-levelfront matterrequired
supersedesfront matterrequired
superseded_byfront matterrequired
Context and problemsectionrequired
Decision driverssectionoptional
Options consideredsectionrequired
Decisionsectionrequired
Consequencessectionrequired
Confirmationsectionrequired
Evidencesectionrequired
Owner decisionsectionoptional

Example

A filled-in copy for an invented product, templates/examples/adr.md, in the Hub repository.It shows the level of detail to aim for, not text to reuse.

example-adr.md
---
template: adr/2
id: ADR-0002
title: Store notes as plain files in Git
status: proposed
date: 2026-03-02
decision-makers: Product Owner
owner-level: yes
supersedes: ~
superseded_by: ~
---
# ADR-0002: Store notes as plain files in Git
## Context and problem
Fieldnotes must keep a user's notes for years and let two people edit them offline. The first prototype kept notes in a
database. Users asked to read and back up their notes without the app.
## Decision drivers
- FR-3: a user can export everything without the app.
- FR-2: two people edit offline and merge later.
## Options considered
1. **Plain Markdown files in a Git repository** — one file per note.
2. **A relational database** — one row per note, export on demand.
3. **Keep the current approach** — a database with a JSON export.
## Decision
Notes are plain Markdown files in a Git repository, because it meets FR-3 and FR-2 without extra code. The database is
kept only as a search index that can be rebuilt from the files.
## Consequences
- Good: users can read, back up and merge notes with ordinary tools.
- Bad / cost: search needs an index that is rebuilt on change.
- Follow-up work: write the index builder (FR-2) and a conflict screen (FR-2).
## Confirmation
`tests/test_export.py` creates a note, deletes the index and reads the note back from the file alone. It runs in every pull request.
## Evidence
Prototype measurements, 2026-02-20: 10 000 notes index in 4 s. Interviews with five testers, notes in `research/2026-02-testers.md`.
## Owner decision
Not yet decided. The owner records the outcome here with a date; until then the status stays `proposed`.

Completion checks

A copy is complete when:

  • every required field and section above is present, in the same order, and no bracketed placeholder is left;
  • the template's comments are deleted from the copy;
  • python3 .uask/hub/tools/check_artifacts.py . reports no failure for it: front matter, sections, ids, leftover placeholders and comments (tools/check_artifacts.py, in every release bundle);
  • the exit criteria of stage 6 of the playbook Project foundation are met;
  • the owner has approved it, where the playbook asks for approval. Only the owner sets approved.

Source

templates/adr.md, as in the repository. Placeholders are in square brackets; comments carry the instructions.

adr.md
---
template: adr/2
id: ADR-NNNN
title: Short decision title
status: proposed # proposed | accepted | rejected | deprecated | superseded — agents write proposed only
date: YYYY-MM-DD
decision-makers: Product Owner # who decides and, while proposed, who will accept it (arch.adr#R9); consulted and informed MAY follow
owner-level: yes # yes | no — yes for a hard-to-reverse architecture choice, the technology stack included; unsure means yes (arch.adr#R10)
supersedes: ~
superseded_by: ~
---
# ADR-NNNN: Short decision title
<!-- Template from the UASK Engineering Hub, version 2, based on MADR 4 (https://adr.github.io/madr/) and item arch.adr
2.0.0. Save as project/decisions/NNNN-short-title.md (next free number, never reused).
Rules: item arch.adr; when it is written: playbook mgmt.project-foundation, stage 6.
The earlier version is templates/adr-v1.md; a record without `template:` is checked against it, and a closed
one (accepted, superseded, deprecated, rejected) is history and stays as it is.
Sections marked "Optional" may be deleted; delete these comments when the record is written. -->
## Context and problem
<!-- What forces the decision, in two to five sentences, as neutral facts. Link the issue and the
requirement ids (FR-n, NFR-n) it serves. -->
## Decision drivers
<!-- Optional. The criteria the options are judged by, e.g. NFR-2 build time, licence, team skills. -->
- …
## Options considered
<!-- At least two real options; include "keep the current approach" where it is viable. -->
1. **Option A** — one line.
2. **Option B** — one line.
## Decision
<!-- The outcome: the chosen option and the reason in one paragraph. While proposed, this is the recommendation. -->
## Consequences
- Good: …
- Bad / cost: …
- Follow-up work: …
## Confirmation
<!-- How the implementation will be confirmed, and where that check lives: a test, an automatic check (a rule of
arch.fitness-functions), a review point with its date, or a measurement. Required for an owner-level
record (arch.adr#R12); for any other record write the check, or "none: reversible, local". -->
## Evidence
<!-- Sources with access dates, measurements, spikes, research notes. -->
## Owner decision
<!-- Optional while proposed. The owner records the outcome here with a date, e.g.
"Accepted by the Product Owner on YYYY-MM-DD (issue #n)." and changes status.
A retrospective record (the decision was taken, and perhaps built, before this file existed): the agent
writes it as proposed and names the earlier decision here, e.g. "Decision in force since YYYY-MM-DD
(source: <dated file or message>); recorded afterwards on YYYY-MM-DD; awaiting the owner's confirmation of
this record." Do not backdate `date:` in the front matter. -->