Skip to content

0001 decision records

github-actions[bot] edited this page Nov 17, 2026 · 1 revision

Decisions are recorded as ADRs

Status: accepted · Implementation: done · Date: 2026-11-17

Context

librelifts starts from an empty repository. The choices made now (license, scope, platforms, where data lives) shape everything after, and the reasons are easy to lose once code exists.

Decision

Every decision that shapes the project gets a short record in docs/decisions/, in the format Spotcraft uses:

  • One file per decision, named NNNN-kebab-title.md, numbered in order.
  • Frontmatter: title, number, status, implementation, date, supersedes, superseded_by, notes.
  • Three sections: Context, Decision, Consequences.
  • A changed decision gets a new record that supersedes the old one. Old records are never rewritten; only their status and superseded_by change.
  • docs/decisions/README.md lists every record with its status.

Consequences

  • A decision costs a few minutes of writing before it is acted on.
  • The history of why things are the way they are stays in the repository, next to the code.
  • Superseded records stay, so the folder also shows what was tried and dropped.

Clone this wiki locally