Duolith docs

0001. Record architecture decisions

  • Status: Accepted
  • Date: 2026-11-14
  • Decided by: Mik (Build plan, rule 5)

Context

The framework is built by agents that start cold. Without a written record, a future session cannot tell a deliberate choice from an accident, and will either re-argue it or break it.

Decision

Every significant choice gets a numbered record in docs/decisions/, using 0000-template.md: context, decision, alternatives and consequences. Records are never edited after acceptance except to change their status; a new record supersedes an old one and links to it.

"Accepted (provisional)" marks a decision taken on a recommendation while Mik's answer is pending. It is binding for implementation and reversible by Mik with a superseding record.

Alternatives considered

OptionWhy not
Decisions in pull request descriptionsNot findable by an agent in a fresh workspace
A single decisions log fileGrows into a wall; individual records can be linked and superseded

Consequences

Agents must check docs/decisions/ before changing anything a record covers, and write a record for any choice a future reader would question (definition of done).