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 section | Where | Required |
|---|---|---|
template | front matter | required |
id | front matter | required |
title | front matter | required |
status | front matter | required |
date | front matter | required |
decision-makers | front matter | required |
owner-level | front matter | required |
supersedes | front matter | required |
superseded_by | front matter | required |
| Context and problem | section | required |
| Decision drivers | section | optional |
| Options considered | section | required |
| Decision | section | required |
| Consequences | section | required |
| Confirmation | section | required |
| Evidence | section | required |
| Owner decision | section | optional |
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.
---template: adr/2id: ADR-0002title: Store notes as plain files in Gitstatus: proposeddate: 2026-03-02decision-makers: Product Ownerowner-level: yessupersedes: ~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 adatabase. 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 iskept 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.
---template: adr/2id: ADR-NNNNtitle: Short decision titlestatus: proposed # proposed | accepted | rejected | deprecated | superseded — agents write proposed onlydate: YYYY-MM-DDdecision-makers: Product Owner # who decides and, while proposed, who will accept it (arch.adr#R9); consulted and informed MAY followowner-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. -->