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.