Skip to content

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.