Architecture Decision Records

This directory contains short, dated records of meaningful design decisions. Each ADR captures one decision, the context it was made in, the alternatives considered, and the consequences accepted. The goal is auditable reasoning, not exhaustive documentation.

Format: Michael Nygard’s template, kept short.

Index

• 0001 — Just-in-time auth
• 0002 — Use Bundler’s lockfile parser
• 0003 — Prefer bug_tracker_uri over source_code_uri
• 0004 — Use OAuth Device Flow, not PATs
• 0005 — Render labels verbatim
• 0006 — Ship as a standalone gem, not a Bundler plugin
• 0007 — Show CONTRIBUTING; don’t parse it
• 0008 — Use Rooibos for the TUI layer
• 0009 — Top-level namespace is GemContribute

When to add an ADR

Add one when a decision is non-obvious and would be expensive to reverse. Don’t add one for “we used Minitest.” Do add one when “we picked X over Y for non-obvious reasons and someone six months from now will wonder why.”