# ADR System — Research Phase

_Last updated: 2026-07-03_

This directory captures research for standardizing how Architecture Decision Records (ADRs)
are organized and used across the user's projects, as a precursor to building a Claude Code
plugin that automates ADR creation and relevance-scoped retrieval. **Nothing here is built
yet** — this is the survey/research phase only, requested to answer "what do we have, and what
could we have with a little engineering elbow grease."

- **`01-current-state-survey.md`** — audit of every project under `~/dev/`, `~/clients/`, and
  `~/projects/` for existing ADR practices (organization, templates, tooling, or absence
  thereof).
- **`02-external-research.md`** — research on ADR best practices generally (Nygard, MADR,
  Y-Statements, lifecycle/governance) and on how Claude Code / AI-agent users specifically have
  integrated ADRs into their workflow.
- **`03-synthesis-and-opportunities.md`** — synthesis answering the three "how might we" goals
  (know when to create/query, systematize creation for consistency, and query with high
  relevance/low bloat) and naming concrete design options for a future `os-adr` plugin.

Provenance note: `02-external-research.md` cites web sources gathered by research agents in a
single pass; several specific tool/repo names and one incident anecdote are flagged inline as
**[unverified]** because they were not independently checked against the primary source in this
pass. Verify before depending on any specific tool name in that file.