cc-os/docs/adr-system/01-current-state-survey.md

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