suleymanbyzt Record Decision
Goal: six months from now, "why did we do it this way?" has a written answer — including what was rejected and why.
A journal entry says what was done. A decision record says what was chosen, what was not, and why. They answer different questions.
When to record
Record a decision when the project hit a real fork in the road:
- Two or more viable approaches existed and one was chosen.
- A technology, library, or pattern was adopted — or deliberately rejected.
- A contract, schema, or architectural boundary changed shape.
- Any L3 task (these always get a decision record).
Do NOT record routine choices that follow from existing conventions. If there was no real alternative, there is no decision to record.
Steps
Write the record to
docs/decisions/NNNN-<slug>.mdusingtemplates/decision.md.NNNNis the next sequence number (0001, 0002...). Half a page maximum. It must contain:- Context — the problem that forced a choice, in two sentences.
- Decision — what was chosen, stated plainly.
- Alternatives — each serious option and the one-line reason it lost.
- Consequences — what this makes easier, what it makes harder, what risk is accepted.
Keep it immutable. A decision record is a point-in-time fact. If the decision changes later, write a NEW record and mark the old one
Superseded by NNNN— never rewrite history.Link it from the task's journal entry, and mention it in your Done report:
Recorded: <journal> + docs/decisions/NNNN-<slug>.md.
Do not
- Do not write a record for every task — that buries the real decisions.
- Do not omit the rejected alternatives. "We chose X" without "over Y, because Z" is half a record.
- Do not edit an accepted record to match a new reality. Supersede it.