cc-os/docs/adr-system/03-synthesis-and-opportunities.md

# Synthesis: What We Have, What We Could Have

_Last updated: 2026-07-03_

This draws on the full survey: 15 `~/dev/` projects plus the `~/clients/`/`~/projects/`
addendum (4 + 2 more) in `01-current-state-survey.md`.

## What we have

- **9 of 21 surveyed projects (~43%)** already write ADR-like content, in **at least 5 distinct
  organizational shapes** (monolithic ADR-style file, one-file-per-decision, dated single
  files, prose embedded in design docs, and — newly found in the addendum — a monolithic
  client-facing `DECISIONS.md`) and **no two identical templates**.
- **A clear split by project category emerged from the addendum**: `~/dev/` personal/tooling
  projects lean one-file-per-decision under `docs/adr/`/`docs/decisions/` with an
  Accepted/Superseded lifecycle framing; `~/clients/` projects lean a single monolithic
  `DECISIONS.md` at repo root with a business-framed `Status: Confirmed/Deferred` field, sized
  for a much smaller decision count (2–14, vs. cc-os's 19); `~/projects/` (personal, non-client)
  skew toward phase/incident narrative logs with no Status field at all, closer to a worklog
  than an ADR. A plugin should treat these as legitimate distinct modes, not force one shape
  onto all three categories.
- **cc-os itself is the edge case that triggered this research**: 19 ADRs in one 601-line file
  — external research found no evidence of a monolithic log surviving much past ~30 decisions
  in practice, so this file is trending toward the point where it needs to become per-file.
- **12 of 21 projects have zero ADRs** (~57%, consistent across every category). These are
  onboarding candidates for later, not now (per this repo's own build-first/
  migrate-incrementally precedent, ADR-013).
- **No project uses any ADR tooling** (adr-tools, log4brains, etc.) — everything is
  hand-authored markdown, which means a plugin has a completely clean slate; it isn't competing
  with or having to migrate off an existing tool.
- **Supersession tracking is the weakest point everywhere** — every project invented its own ad
  hoc mechanism (inline prose note, a "delete this when" condition, a status column in an
  index, an explicit status field) and none of them is machine-checkable.

## What we could have (with engineering effort)

A standardized ADR system, informed by the external research, would need to solve three
separate problems — matching the three HMWs in the original request:

### HMW 1 — Know when to create or query ADRs

**Deterministic triggers beat AI judgment where possible.** The research surfaced a workable
split:
- **Query trigger**: path-based, deterministic, cheap. A hook (SessionStart or a
  pre-edit check, matching cc-os's existing lazy-freshness pattern from ADR-007) matches the
  file(s) about to be touched against each ADR's declared "affected paths" or component tags,
  and injects only ADRs that match — no LLM call needed for the common case. This mirrors
  adr-kit's `adr-watch`/`adr-context` pattern found in the research.
- **Create trigger**: harder to make fully deterministic, since "was this decision
  significant" is a judgment call. The realistic pattern (per Spotify's guidance and the
  adr-kit `/adr:review` pattern) is a **semi-automated nudge**: a lightweight heuristic (e.g. a
  diff touching more than N files across more than one module, or touching a path with no
  covering ADR) flags "this might warrant an ADR," and the AI or user makes the actual
  create/skip call. Fully automatic creation risks the "ADR spam" pain point noted in the
  research.

### HMW 2 — Systematize creation for consistency and quality

- **Pick one template per mode, not a free-for-all.** The survey shows template drift is the
  core mess *within* this user's own projects, not just across the industry. A plugin should
  ship **two canonical field sets**, not one, matching the two legitimate shapes the survey
  found:
  - **Tooling/personal-project mode** (`~/dev/`-style): Nygard's minimal fields (Status ·
    Context · Decision · Consequences) plus an explicit Alternatives-rejected field (valuable
    in 3/6 `~/dev/` projects and repeatedly emphasized in the external research as the
    highest-value-per-word field). Full MADR RACI metadata (Deciders/Consulted/Informed) is
    solo-freelancer overkill.
  - **Client-project mode** (`~/clients/`-style): a lighter monolithic-file template —
    date+title heading, `Status: Confirmed/Deferred`, `Category:`, short Reasoning — matching
    what `philly-search-engine-marketing`'s already-working `DECISIONS.md` does, rather than
    imposing per-file/`docs/adr/` overhead on a 2–14-decision client engagement.
  A plugin should pick the mode from project shape (client dir vs. tooling repo, or a simple
  flag) rather than forcing every project through the same template.
- **One-file-per-decision + index for tooling-mode projects; single-file for client-mode.**
  Tooling-mode should auto-generate the next sequence number and append a row to an index file
  — mechanical, no LLM needed — matching the pattern that already recurs in
  viking-warrior-training-log and llf-schema, and that the external research says holds up at
  scale (cc-os's own monolithic file is the outlier now hitting the predicted wall). Client-mode
  should keep appending to one `DECISIONS.md`, since the surveyed client files (2–14 decisions)
  are nowhere near the scale where that becomes a problem.
- **Formalize supersession as a real field**, not prose. `supersedes: ADR-NNNN` /
  `superseded-by: ADR-MMMM` frontmatter, checked/updated mechanically when a new ADR declares
  `supersedes:` — closing the weakest gap found in every single surveyed project.

### HMW 3 — Query with high relevance, low bloat

This is where the research most directly hands cc-os a design option it wasn't otherwise
going to consider: **ADRs as another node type in the already-adopted Graphify knowledge graph
(ADR-010)**, rather than a separate retrieval mechanism. Concretely, this suggests layering,
cheapest-first:
1. **Deterministic path/component match** (an ADR's frontmatter declares affected
   paths/components; a hook filters by the files in the current diff/task) — zero LLM cost,
   handles the majority case.
2. **Status filter** — only `Accepted` ADRs surface by default; `Proposed`/`Superseded` stay
   out of default context, available on explicit query only.
3. **Graph traversal** (once ADRs are indexed alongside code/doc nodes) for the harder case —
   "what decisions structurally relate to this one," not just "what decisions touch this file."
   This reuses infrastructure cc-os already has rather than standing up a parallel vector/RAG
   system.
4. **AI relevance judgment as the last resort**, only over the already-narrowed candidate set
   from steps 1–3 — never over the full ADR corpus. This is the concrete mechanism for "avoid
   cluttering the context window... without simultaneously suppressing the relevant ones."

## Open questions to resolve before building

- Does an `os-adr` plugin apply retroactively to cc-os's own 19-ADR file (a live migration), or
  ship fresh and get piloted on a new/small project first, per the build-first/
  migrate-incrementally precedent already established for the vault (ADR-013)? Recommend the
  latter for consistency.
- Should ADR affected-path/component metadata be authored by hand (like Graphify hub notes,
  per ADR-014's finding that connective structure must be human-authored) or can it be inferred
  automatically from the diff that prompted the ADR? Given ADR-014's empirical finding that
  Graphify does not auto-cluster topics, the safer default is human-authored metadata at
  creation time, not inferred after the fact.
- Where does an ADR "index" live if projects don't all use Graphify yet (9 of 15 surveyed
  projects have never been onboarded) — does the plugin need a project-independent fallback
  (a plain generated `README.md` table) so it's useful even before Graphify onboarding?
- **Resolved by the addendum**: client-owned repos do impose different constraints. Confirmed
  pattern: client projects favor a single readable `DECISIONS.md`, business-framed
  Confirmed/Deferred status, and no per-file/subdirectory ceremony — matching a freelance
  handoff need (a client or collaborator can open one file, no plugin/CLI required to read it).
  A plugin must not force the `~/dev/` per-file convention onto client engagements.

## Recommendation

Treat this as a future OpenSpec change (`openspec-propose`), not something to build ad hoc off
this research doc alone. The research here (now including the `~/clients/`/`~/projects/`
addendum) is sufficient to write a design doc / ADR of its own (an ADR about how to do ADRs,
covering both the tooling-mode and client-mode template/organization split) when that time
comes.