Engineering decisions

The record of the choices the code already depends on. A person arriving here should be able to read these in order and know why the repository, the providers, the builds and the runtime look the way they do — without reading eight specs to find the one sentence that settled it.

The specs say what the product does. These say what was decided, when, and on whose word.

The convention

One file per decision, named NNNN-slug.md — four digits in order of acceptance, and the number never changes. Each file is short, and carries four sections:

Every record carries its date — the date the decision was made, which is often older than the day someone wrote it down.

A record stops changing once it is accepted. A decision that moves gets a new record, and the old one gains one line at the top naming its successor. That is the whole mechanism: the history stays readable because nothing is quietly rewritten.

The Source section carries a real citation. A FEED-IA § number, a spec heading, a file path, a GitHub setting with its date. A decision nobody can trace is a decision nobody can reopen.

What lives elsewhere

• decisions/ in Rocoto-Labs/company is the company's own record — market, pricing, positioning, the pivots — under its own dated-filename convention, in its own repository (record 0010).
• The specs (docs/THE-*-SPEC.md) hold the contract itself. A record here points at the spec section; it never restates it.
• Peter's directives live verbatim and numbered in docs/FEED-IA.md (historical reference outside this export). A record quotes the § number and leaves the words where they are.

The records

Source document ↗