# 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.