From f8bb78924edb07e37ec3a730cb72c8557c5397f7 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 11 Oct 2026 20:26:11 +0000 Subject: [PATCH] Clarify the scope of architectural decision records --- docs/policy/documentation.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/policy/documentation.md b/docs/policy/documentation.md index 67b8a9a..9c223f7 100644 --- a/docs/policy/documentation.md +++ b/docs/policy/documentation.md @@ -2,7 +2,7 @@ **Base Policy Version:** 1.11 -**Last Updated**: 2026-10-06 +**Last Updated**: 2026-10-10 **Upstream Source:** [documentation.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/documentation.md) @@ -147,6 +147,15 @@ mechanisms only. ## Architecture Decision Records +ADRs record durable architectural decisions: responsibility boundaries, +ownership, significant constraints, and the reasons for choosing them. A settled +implementation or presentation choice does not automatically belong in an ADR. +Ask whether changing the detail would alter the architecture or represent +reasonable evolution within it. Details that can evolve within the chosen +architecture belong in API or CLI contracts, implementation documentation, or +roadmaps. Describe upstream behavior as context without turning it into an +independent project guarantee. + Use sequentially numbered ADR filenames such as `0001-record-architecture-decisions.md`. Follow the lightweight Nygard format: