0001 Record decisions as decision records¶
Source: #493
Context and Problem Statement¶
Lasting decisions lived in issues, in PRODUCT.md and in old discussions. People and AI agents could not see the reasons. They could undo a decision by accident. "pivotkit has no scheduler" was one example: it lived in #165 and PRODUCT.md.
Some decisions span pivotkit and its host integrations, such as the PowerShell Universal module. They need one place too.
Considered Options¶
- Keep decisions in issues and PRODUCT.md (not discussed in a source).
- Record each decision as an Architecture Decision Record in
docs/decisions/.
Decision Outcome¶
Chosen option: decision records in docs/decisions/, in the minimal template of
MADR.
- One decision per file, numbered, about one page.
- Each record links its issue or pull request. Work and task state stay in issues.
- An accepted record is not edited. A change is a new record that supersedes or amends the old one. Both link each other.
- Reversible choices with little impact get no record.
- Decisions that span pivotkit and its host integrations live here too. The PowerShell Universal repository links to them.
Status means:
| Status | Meaning |
|---|---|
| accepted | binding. A task that conflicts with it stops and proposes a new record |
| proposed | context. Not binding yet |
| superseded | history. It links the record that replaced it |
Where no source gives the reason, a record says "reason not recorded".
A record's date is the day it was accepted. A proposed record carries the day it was proposed. The
pull request that brings its behaviour to main sets it to accepted and updates the date.
Consequences¶
- Good: anyone can check a task against the accepted records before it starts.
- Good: one place for decisions of pivotkit and its host integrations.
- Bad: the records and the index need upkeep.