writing-adrslisted

# Writing Architecture Decision Records ## Overview Architecture Decision Records (ADRs) capture significant technical decisions in a concise, standardized format. They answer "why did we do this?" for future developers and AI agents. DorkOS ADRs live in `decisions/` with a `manifest.json` index. ## When to Write an ADR Write an ADR when a decision: - **Chooses between alternatives** — "We picked X over Y because..." - **Adopts a pattern or technology** — New library, architecture pattern, data model - **Has lasting consequences** — Affects how future features are built - **Would surprise a new team member** — Non-obvious choices that need explanation ## When NOT to Write an ADR Skip ADRs for: - **Trivial implementation details** — Variable naming, file placement within an established structure - **Obvious choices** — Using TypeScript in a TypeScript project - **Temporary decisions** — Workarounds that will be replaced soon - **Single-feature scope** — Decisions that only affect one spec with no project-wide impact ## Writing Guidelines ### Context (2-5 sentences) Focus on the **problem**, not the solution. What situation existed? What forces were at play? - **Good**: "DorkOS runs as both a standalone web app and an Obsidian plugin. The Obsidian plugin cannot make HTTP requests to localhost, so the client needs a way to communicate with the server that works in both environments." - **Bad**: "We needed an architecture." (Too vague) - **Bad**: A full page of backgr