From 5d5145f347c4b05f8e2bd6ff5aa4888e9a2043ec Mon Sep 17 00:00:00 2001 From: jared Date: Fri, 3 Jul 2026 11:55:12 -0400 Subject: [PATCH] Add ADR system research and design analysis Research into current ADR practices across projects, external best practices, and design opportunities for the future os-adr plugin. --- docs/adr-system/00-README.md | 24 +++ docs/adr-system/01-current-state-survey.md | 189 ++++++++++++++++++ docs/adr-system/02-external-research.md | 178 +++++++++++++++++ .../03-synthesis-and-opportunities.md | 130 ++++++++++++ 4 files changed, 521 insertions(+) create mode 100644 docs/adr-system/00-README.md create mode 100644 docs/adr-system/01-current-state-survey.md create mode 100644 docs/adr-system/02-external-research.md create mode 100644 docs/adr-system/03-synthesis-and-opportunities.md diff --git a/docs/adr-system/00-README.md b/docs/adr-system/00-README.md new file mode 100644 index 0000000..9ceb5fb --- /dev/null +++ b/docs/adr-system/00-README.md @@ -0,0 +1,24 @@ +# 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. diff --git a/docs/adr-system/01-current-state-survey.md b/docs/adr-system/01-current-state-survey.md new file mode 100644 index 0000000..df25f70 --- /dev/null +++ b/docs/adr-system/01-current-state-survey.md @@ -0,0 +1,189 @@ +# Current-State Survey: ADR Practices Across `~/dev/` Projects + +_Last updated: 2026-07-03_ + +Survey of every project directory under `~/dev/` for existing Architecture Decision Record +practices. Read-only audit; no files were changed. Source: agent survey, 2026-07-03. + +## Projects with formal ADRs + +### cc-os +- **Organization**: monolithic — `docs/memory-system/03-architecture-decisions.md`, 601 lines, + 19 ADRs (this repo, before this research phase). +- **Naming**: `ADR-NNN` heading per entry within the single file. +- **Template fields**: Context · Decision · Rationale · Alternatives rejected · Status. + Supersession noted inline ("Superseded by ADR-010", "Refined by ADR-011"). +- **Tooling**: none; plain markdown. `_Last updated:_` date at top of file. + +### viking-warrior-training-log +- **Organization**: one file per decision — `docs/adr/`, 6 files + `README.md` index. +- **Naming**: `NNNN-kebab-case-title.md` (e.g. `0001-pocketbase-backend.md`). +- **Template fields**: Status · Date · Context · Decision · Consequences · Alternatives + considered. Files are 30–41 lines. +- **Tooling**: `README.md` index — a table of all ADRs with title + status. Explicitly notes + ADRs 0001–0003 were backfilled after the fact; 0004–0006 record refinements after critique. +- **This is the only project with both per-file organization AND a maintained index.** + +### delta-refinery +- **Organization**: one file per topic (not numbered) — `docs/decisions/`, 12 files, 25–48 + lines each. +- **Naming**: topic-driven kebab-case (`bin-lint-fix.md`, `map-driven-design-system.md`). +- **Template fields**: Status · Decided (date) · Decision · Why · What Was Built (artifact + table) · Open Questions · **"Delete this document when"** (a sunset/supersession condition + instead of an explicit supersedes/superseded-by field). +- **Tooling**: none. + +### design-mode +- **Organization**: one file, dated — `docs/decisions/2024-12-jsx-conversion-pivot.md` (only 1 + decision recorded), 78 lines. +- **Naming**: `YYYY-MM-topic-kebab.md`. +- **Template fields**: Date · Status · Context · Problem · Decision · Implementation + (Keep/Remove/Update subsections) · Open Questions · **Lessons Learned** (a retrospective + field not seen elsewhere in this survey). +- **Tooling**: none. + +### llf-schema +- **Organization**: mixed — `docs/decisions/`, 6 files (18–134 lines), but several files + embed *multiple* numbered decisions rather than one-per-file. +- **Naming**: `YYYY-MM-DD-topic-kebab.md` at the file level; `D-NNN` numbering for individual + decisions embedded within a file (at least D-038 through D-043+ found). +- **Template fields**: Status · Context · Decision · Consequences; some have an "Open + sub-decision" pattern with explicit options + rationale. +- **Tooling**: cross-links into the project's `openspec/changes/...` spec-driven change + system — the only project doing this. One file (`2026-06-04-plugin-decision-index.md`) acts + as a superseded historical index pointing to newer sub-documents. + +### cc-plugins +- **Organization**: decisions embedded in prose within larger design docs, not a dedicated + ADR directory. `progressive-disclosure/docs/gaps-and-decisions.md` (297 lines) numbers + decisions inline ("Decision 26: Single entry point"). +- **Template fields**: narrative Decision / Why / mechanics — no structured Status/Context + fields as distinct headings. +- **Notable**: the whole document is marked `(LOCKED)` — a document-level freeze convention + instead of a per-decision status field. + +## Projects without formal ADRs + +| Project | Notes | +|---|---| +| playground | No `docs/`; minimal project. | +| remetrics | Has a README; no decision docs. | +| ruby-gems | Umbrella dir, 10 sub-repos checked; none have ADRs. | +| thinkfast | CLAUDE.md references "architectural decisions" as a task category but no ADR files exist. | +| verona-vocab | Has CLAUDE.md; no decision docs. | +| websites | Umbrella dir (hyperthrive, hyperthrive-strategy checked); none have ADRs. | +| wordpress-dc | No `docs/`. | +| hyperthrive_dev | Uses ad hoc `.scratch/active/progress.md` subagent handoff logs instead of ADRs. | +| llf-schema-build-tmp | Throwaway build directory, not a persistent project — excluded from future onboarding. | + +## Addendum: `~/clients/` and `~/projects/` + +The first pass covered `~/dev/` only. A second pass surveyed `~/clients/` +(inovis-lighting-audit-manager, philly-search-engine-marketing, summit-new-hire-automation, +virtuosocontent) and `~/projects/` (niche-automation-prospecting, taxes-swanson). This surfaced +a **distinct organizational pattern from `~/dev/`** — worth treating as its own category, not +merging into the table above. + +### Client projects (`~/clients/`) + +- **inovis-lighting-audit-manager**: no ADRs, nothing adjacent. +- **philly-search-engine-marketing**: monolithic root-level `DECISIONS.md` (236 lines, 14 + decisions), plus two secondary dated docs for specific incidents. Per-decision fields: date + + title heading, `Status:` (Confirmed/Deferred), `Category:` ([Tech]/[Business]), `Source:` + (attribution), then narrative Goal/Decision/Reasoning/Residual-or-Deferred-notes. Explicitly + referenced from `CLAUDE.md`'s quick-reference table as "Past decisions" — i.e. treated as a + canonical, actively-pointed-to file. +- **summit-new-hire-automation**: not really an ADR — one post-hoc "decision framework" + document (n8n vs Rails) that's a retrospective/lessons-learned analysis of a platform choice + already made, including a decision matrix and red-flag checklist for future similar choices. + ADR-adjacent, not an ADR. +- **virtuosocontent**: monolithic root-level `DECISIONS.md`, but minimal — 10 lines, 2 + decisions, just a date+title heading and a one/two-line factual statement (no Status, + Category, or reasoning fields at all). + +### Personal/internal projects (`~/projects/`) + +- **niche-automation-prospecting**: no dedicated decisions file; decisions are scattered inside + timestamped working documents — `logs/increments/2026-05-26-*-decisions.md` and a + `PHASE4-DECISION-MEMO.md` — organized by project phase/event (executive summary, tier + score-snapshot tables, "clear kills," next steps) rather than as discrete Status-tagged + entries. ~20 decisions total across the two files, but as narrative sections, not an ADR list. +- **taxes-swanson**: no ADRs, nothing adjacent. + +### What's different here vs. `~/dev/` + +1. **Client projects favor one monolithic root-level `DECISIONS.md`, not a `docs/decisions/` or + `docs/adr/` directory** — the opposite of the `~/dev/` majority pattern (one-file-per-decision + in a subdirectory). Likely driver: a client-facing single readable log is easier to hand off + or reference during a client conversation than a directory of numbered files, and these + projects are shorter-lived/smaller in decision count (2–14) than cc-os's 19. +2. **Client `DECISIONS.md` files use a `Status:` field (Confirmed/Deferred) that tracks whether + a decision is still locked-in — a business/client-relationship framing** distinct from the + Accepted/Superseded lifecycle framing used in `~/dev/` (ADR-013/ADR-018-style projects). +3. **Internal (`~/projects/`) decision-adjacent docs skip Status entirely** and are organized as + phase/incident narratives (a "worklog," not an architectural record) — closer to + hyperthrive_dev's `.scratch/active/progress.md` pattern from the `~/dev/` survey than to any + ADR convention. +4. **The no-ADR baseline holds**: 3 of 6 (`inovis-lighting-audit-manager`, `taxes-swanson`, and + arguably `summit-new-hire-automation`) have nothing ADR-like, roughly matching the ~60% + no-ADR rate found across `~/dev/`. + +**Implication for plugin design**: a future `os-adr` plugin likely needs **two supported +shapes**, not one-size-fits-all — a lightweight monolithic `DECISIONS.md` mode (small +decision counts, client-facing/handoff-friendly, business Confirmed/Deferred status framing) +alongside the per-file `docs/adr/`+index mode recommended for larger personal/tooling projects. +Forcing the `~/dev/`-style per-file convention onto a 2–14-decision client project would likely +be over-engineering relative to what those projects need. + +## Cross-project comparison + +**Organization pattern, by frequency:** +1. One file per decision in a dedicated directory — viking-warrior-training-log, llf-schema + (partially), design-mode (only 1 file so far, same shape). Most common approach once a + project has more than a couple of decisions. +2. Monolithic single file — cc-os only, and only this repo has reached a high ADR count (19) + while staying in one file; still, that file is now 601 lines and prompted this research. +3. Embedded in prose within other docs — cc-plugins. Lowest discoverability; no per-decision + status field. + +**Naming, by frequency:** +- Sequential numeric (`0001-`, `ADR-NNN`, `D-NNN`): cc-os, viking-warrior-training-log, + llf-schema — 3 of 6. +- Topic-only kebab-case, no number: delta-refinery. +- Date-prefixed: design-mode, llf-schema (at the file level). +- Inline prose numbering: cc-plugins. + +**Template fields, by prevalence (of the 6 projects with any ADR-like content):** +| Field | Count | Projects | +|---|---|---| +| Decision | 6/6 | all | +| Status | 5/6 | all but cc-plugins | +| Context | 5/6 | all but cc-plugins | +| Consequences | 4/6 | viking-warrior-training-log, design-mode, llf-schema, cc-plugins ("Why") | +| Alternatives (rejected/considered) | 3/6 | cc-os, viking-warrior-training-log, design-mode | +| Rationale | 2/6 | cc-os, delta-refinery | +| Date | 4/6 | viking-warrior-training-log, delta-refinery, design-mode, llf-schema | + +**Key observations:** +- **No two projects use an identical template** — field names and ordering vary even where the + underlying concept (e.g. "why we rejected X") is the same. +- **Supersession handling is ad hoc everywhere**: cc-os uses inline prose notes, + delta-refinery uses a sunset condition ("delete this document when…"), viking-warrior- + training-log uses a status column in its index, llf-schema uses an explicit + open/settled status field. No project has a formal `supersedes:` / `superseded-by:` field. +- **Indexing is rare**: only viking-warrior-training-log (README table) and cc-plugins (a + locked index-like document) have anything resembling a discoverability index. Every other + project relies on `ls`/grep of the directory. +- **None of the 6 projects use ADR tooling** (adr-tools, log4brains, etc.) — all are + hand-authored markdown. +- **9 of 15 `~/dev/` projects have no ADRs at all** — future onboarding candidates once a + plugin exists (per this repo's own ADR-013 precedent: build-first, then migrate/onboard one + project at a time rather than batch-migrating everyone). Across the `~/clients/`+`~/projects/` + addendum, 3 of 6 also have none — a consistent ~55-60% no-ADR baseline across every category + surveyed. +- **Client-facing and personal/internal projects (see addendum above) use a visibly different + shape than `~/dev/` tooling projects**: a single monolithic root `DECISIONS.md` rather than a + per-file directory, smaller decision counts (2–14 vs. cc-os's 19), and — for client + projects — a business-framed `Status: Confirmed/Deferred` field rather than an + Accepted/Superseded lifecycle field. A future plugin needs to support this as a distinct, + legitimate mode, not treat it as an under-developed version of the `~/dev/` pattern. diff --git a/docs/adr-system/02-external-research.md b/docs/adr-system/02-external-research.md new file mode 100644 index 0000000..cb75495 --- /dev/null +++ b/docs/adr-system/02-external-research.md @@ -0,0 +1,178 @@ +# External Research: ADR Best Practices & Claude Code Integration + +_Last updated: 2026-07-03_ + +Two research passes: (1) general ADR best practices independent of any AI tooling, (2) how +Claude Code / AI-coding-agent users specifically have integrated ADRs. Gathered by web-research +agents, 2026-07-03. Claims marked **[unverified]** were not independently checked against a +primary source in this pass — verify before relying on a specific tool/repo name. + +--- + +## Part A — General ADR Best Practices + +### 1. File/directory organization + +Industry consensus favors **one-file-per-decision** over a monolithic running log, following +Michael Nygard's original 2011 convention: sequential numbered files (`0001-title.md`, …) in +`doc/adr/`, stored alongside code in version control ([Cognitect +Blog](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)). MADR refines +this with timestamped naming for sortability ([MADR docs](https://adr.github.io/madr/)). + +Tradeoffs at scale: +- **Advantages**: immutable per-decision history, shallow git diffs (no merge conflicts on a + shared log file), sequential numbering creates a shared "decision language." +- **Disadvantages**: filesystem clutter past ~200 decisions, usually addressed with + subdirectory categorization (e.g. `decisions/backend/`). + +Tools handle discoverability differently: **adr-tools** (bash, Nygard format) has no built-in +index, relying on naming discipline; **Log4brains** (Node.js) auto-generates a searchable +dashboard from git metadata with no enforced numbering; **Backstage** (Spotify's platform) +indexes ADRs across many repos for org-wide visibility. Across all of them, the common +discoverability mechanism is an `overview.md`/`README.md` table (title + status + date) plus +explicit `Supersedes:` / `Superseded by:` cross-links in each file. + +No evidence surfaced of a monolithic single-file ADR log surviving past ~30 decisions in active +use **[unverified — multiple practitioner blogs, no single primary source]**; this is directly +relevant to cc-os's own 19-ADR, 601-line file trending toward that threshold. + +### 2. Content template best practices + +Three templates dominate: +- **Nygard minimal**: Status · Context · Decision · Consequences. Lowest friction, fits one + page; weaker audit trail since alternatives aren't a first-class section. +- **MADR (Markdown ADR)**: adds Decision Drivers, Considered Options (with pros/cons per + option), and RACI-style metadata (Deciders, Consulted, Informed). Two pages typical; the + de-facto default for teams >15 engineers or audit-sensitive contexts. +- **Y-Statements**: one paragraph — "In the context of ``, facing ``, we + decided for `