Skip to main content

Decisions

Architectural decision records (ADRs), dated, one file per decision. Read these when you need to know why the code is shaped the way it is — the reasons rarely live in comments, and the git log rarely gives enough context.

How to use this directory​

  • Before changing a system: grep for the system name (e.g., voice, stripe, rag). If there's a recent ADR, read it — the decision usually has constraints that aren't obvious from the code alone.
  • Before adding a new ADR: use _template.md. Filename is YYYY-MM-DD-<topic>.md. Include: context, options considered, what we picked, consequences (good + bad), date, and — if the decision is later reversed or refined — a superseded-by: pointer in the frontmatter.
  • Never delete an ADR even if superseded. The superseded record is the evidence of why the new path was chosen.

Most-referenced decisions (start here)​

Chronological (newest first)​

Full list is auto-discovered; grep / sort by filename for the date. The 17 ADRs here span March–April 2026. Each is self-contained; read only the ones relevant to your current question.

  • Processes — long-form process docs (some reference the ADRs that govern them)
  • Architecture — system design docs (ADRs are the "why"; architecture is the "what")
  • DECISION_LOG.md at repo root — rolling session-by-session journal. Short entries, high volume. This directory is the curated long-form version.