Skip to content

Draft — not approved. A working draft by UASK. It may change without notice.

ADR v1

This template is not tied to a playbook stage.

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

How to use

The template's own instructions:

Frozen: version 1 of this template. An artefact without `template:` is checked against it and gets a warning; new work uses templates/adr.md (version 2). Do not edit.

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
idfront matterrequired
titlefront matterrequired
statusfront matterrequired
datefront matterrequired
decidersfront matterrequired
supersedesfront matterrequired
superseded_byfront matterrequired
Context and problemsectionrequired
Decision driverssectionoptional
Options consideredsectionrequired
Decisionsectionrequired
Consequencessectionrequired
Evidencesectionrequired
Owner decisionsectionoptional

Example

A filled-in copy for an invented product, templates/examples/adr.md, in the Hub repository.This template is frozen; the example follows its current version.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 owner has approved it, where the playbook asks for approval. Only the owner sets approved.

Source

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

adr-v1.md
---
id: ADR-NNNN
title: Short decision title
status: proposed # proposed | accepted | rejected | deprecated | superseded — agents write proposed only
date: YYYY-MM-DD
deciders: Product Owner
supersedes: ~
superseded_by: ~
---
<!-- Frozen: version 1 of this template. An artefact without `template:` is checked against it and gets a warning; new
work uses templates/adr.md (version 2). Do not edit. -->
# ADR-NNNN: Short decision title
<!-- Template from the UASK Engineering Hub, based on MADR 4 (https://adr.github.io/madr/).
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.
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
<!-- Chosen option and the reason in one paragraph. While proposed, this is the recommendation. -->
## Consequences
- Good: …
- Bad / cost: …
- Follow-up work: …
## 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. -->