ADRs derived from voice

Architecture Decision Records (ADRs) are the standard pattern for capturing why a system is built the way it is. The pattern usually fails at the writing step — engineers don't want to type up a meeting they just spent an hour in. Transcribing instead makes ADRs free: the decision was already discussed verbally, the transcript captures it verbatim, and the commit is one PR away.

Convert each decision meeting on Audio to Markdown, save as docs/adr/2026-01-15-event-system.md with a short preamble (Context, Decision, Consequences) prepended to the transcript. Commit. The PR review captures dissents that came up post-meeting; the merged file is the canonical record.

Where this lives in the repo

Common conventions: docs/adr/ for canonical decision records, docs/meetings/ for routine standups and status calls (less ceremony), docs/postmortems/ for incident review transcripts. All in GitHub-Flavored Markdown, all rendered nicely on GitHub's file viewer, all searchable via GitHub's code search.

Linking decisions to code

In the relevant code file, comment: // See docs/adr/2026-01-15-event-system.md for the decision context. GitHub renders the path as a clickable link in the file viewer. Future engineers reading the code land on the actual transcript with attribution and context. Pair with PDF to Markdown for GitHub for vendor specs and URL to Markdown for GitHub for reference articles.