Decision records (ADRs)
A place to write down major decisions, the reasoning behind them, and the conditions under which we’d revisit them.
When a decision needs an ADR
Write an ADR when:
- The decision affects more than one person or team
- It’s hard to reverse (or would cost >1 week of work to reverse)
- Annual impact > 10,000 AUD
- It’s a product direction, pricing strategy, supplier change, or structural org change
- Someone will ask “why did we do it this way?” six months from now
Format
Use the ADR template. Name files NNN-short-slug.mdx where NNN is the next sequential number (e.g. 001-supabase-as-catalog-source-of-truth.mdx).
Decisions to backfill
The following are decisions already made that should have an ADR written for them. If you have context on any of these, write it up:
- Why Supabase for the product catalog (vs. keeping everything in Shopify)
- Why Nextra for this handbook (vs. Docusaurus, Notion, GitBook)
- Why Slack for internal comms (vs. Lark, WhatsApp)
- Why SPU + Variant data model (vs. flat SKU per carrier)
- Why gstarlink.com over globalstarlink.com.au
Index
No ADRs yet.