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 section | Where | Required |
|---|---|---|
id | front matter | required |
title | front matter | required |
status | front matter | required |
date | front matter | required |
deciders | 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 |
| Evidence | section | required |
| Owner decision | section | optional |
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.
---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 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.
---id: ADR-NNNNtitle: Short decision titlestatus: proposed # proposed | accepted | rejected | deprecated | superseded — agents write proposed onlydate: YYYY-MM-DDdeciders: Product Ownersupersedes: ~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. -->