Skip to content

Hybrid Evergreen plus ADR Subdirectory

Context

A technology selection guide can be organized in several mutually-exclusive shapes. A "pure evergreen" handbook reads as a single living narrative whose recommendations change in place; a "pure ADR" archive preserves every decision as an immutable, dated record; and a "Tech Radar" rings (Adopt / Trial / Assess / Hold) summarises postures at a glance. Each shape optimises for a different reader: the evergreen serves engineers asking "what should I do today", the ADR archive serves auditors asking "why did we choose this in 2026", and the Radar serves leadership asking "where is our portfolio heading". This guide has all three audiences.

This guide's primary readers are (a) engineers scaffolding a new service, (b) LLM agents grounding recommendations in organisational standards, and (c) adopting orgs forking the artifact. Reader (a) MUST be able to land on a chapter and follow its current recommendation without reading the decision history. Reader (b) MUST be able to ingest a stable narrative surface (chapters) plus a hierarchical index (ADRs) for citation. Reader (c) MUST be able to fork the guide, update the recommendations for their context, and preserve the original decision rationale separately so that future edits do not lose the "why".

A single shape cannot serve all three readers simultaneously without compromise. The guide therefore adopts a hybrid: an evergreen narrative chapter set as the primary reading surface, plus a decisions/ subdirectory of immutable MADR-format ADRs that record the rationale for each macro choice. Chapters MAY be revised in place; ADRs MUST NOT be edited after acceptance (a superseding ADR is added instead).

Decision Drivers

  • The guide MUST serve engineers asking "what should I do today" without forcing them to read decision history.
  • The guide MUST preserve immutable rationale for every macro choice so that forkers and auditors can reconstruct intent.
  • The guide MUST be navigable by LLM agents that consume a chapter index and an ADR index as separate hierarchies.
  • The structure SHOULD minimise the cognitive overhead of "where does new content go" for contributors.
  • The structure SHOULD allow the evergreen surface and the ADR archive to evolve at different cadences (chapters quarterly; ADRs only on new decisions or supersedes).

Considered Options

  • Hybrid: evergreen chapters plus a decisions/ ADR subdirectory
  • Pure evergreen: a single living narrative with no ADRs
  • Pure ADR: every recommendation lives as a dated MADR record
  • Tech Radar: Adopt / Trial / Assess / Hold rings as the primary surface

Decision Outcome

Chosen option: "Hybrid: evergreen chapters plus decisions/ ADR subdirectory", because it is the only option that satisfies all three reader audiences without compromise. The evergreen surface gives engineers a directly-actionable narrative; the ADR archive gives forkers and auditors the immutable "why"; and the two-hierarchy shape gives LLM agents a clean ingestion target. The Tech Radar shape was specifically considered and rejected — it summarises postures but does not preserve rationale and does not provide enough surface for prescriptive prose.

Positive Consequences

  • Engineers MAY read a chapter and follow its recommendations without context-switching into the ADR archive.
  • Forkers MAY edit chapters freely while preserving the original ADR rationale unchanged, then add their own ADRs for divergences.
  • LLM agents MAY index docs/ and docs/decisions/ as separate hierarchies for citation, matching the llms.txt two-section layout.

Negative Consequences

  • Contributors MUST decide whether a change belongs in a chapter, an ADR, or both — this is a non-trivial editorial judgment.
  • The guide carries duplication risk: a chapter MAY summarise an ADR's recommendation, and the two MUST be kept consistent on revisions.

Consequences

After this decision, every macro choice captured during specification SHOULD have a corresponding ADR in docs/decisions/, and every chapter SHOULD cite the relevant ADR(s) where they exist. The quarterly review cadence (see ADR 0004) applies to chapters but not to ADRs — ADRs are revised only by adding superseding records. Contributors MUST treat ADRs as append-only: an accepted ADR MUST NOT have its Decision Outcome rewritten; instead, a new ADR with status: superseded references and replaces it.

Pros and Cons of the Options

Hybrid: evergreen chapters plus decisions/ ADR subdirectory

Two complementary surfaces — chapters for current recommendations and ADRs for immutable rationale.

  • Good, because it serves all three reader audiences without compromise.
  • Good, because it matches the llms.txt two-section index shape cleanly.
  • Good, because forks MAY diverge chapters while preserving original ADRs.
  • Bad, because contributors MUST learn the editorial split between chapters and ADRs.

Pure evergreen

A single living narrative with no ADR archive.

  • Good, because the editorial model is simple — every change goes in the narrative.
  • Bad, because the rationale for past decisions disappears as the narrative is edited in place.
  • Bad, because forkers cannot distinguish "the original org's reasoning" from "the fork's reasoning" without an out-of-band changelog.

Pure ADR

Every recommendation lives as a dated MADR record; there is no evergreen narrative.

  • Good, because every recommendation is dated and rationalised.
  • Bad, because engineers MUST read decision history to find the current recommendation, which violates the "scaffold in hours" goal.
  • Bad, because the surface is fragmented for LLM ingestion — there is no stable chapter to point to.

Tech Radar

Adopt / Trial / Assess / Hold rings as the primary surface.

  • Good, because it gives leadership a single posture-at-a-glance view.
  • Bad, because it does not preserve rationale.
  • Bad, because it does not provide enough surface for the prescriptive prose that engineers and LLM agents need.