From c26acd670b240428563715c9b528286d6317aabb Mon Sep 17 00:00:00 2001 From: fullsend-code <278716306+fullsend-ai-coder[bot]@users.noreply.github.com> Date: Thu, 20 Aug 2026 17:51:47 +0000 Subject: [PATCH] docs(#6423): document extract-to-living-doc pattern for ADRs Add guidance for handling evolving operational details in accepted ADRs. When details like field tables, struct definitions, or merge rules need updating, agents should extract them to a living reference document under docs/contributing/ rather than modifying the ADR. This codifies the pattern already used by docs/contributing/harness-fields.md (which holds evolving field tables from ADR-0045). Changes: - docs/contributing/adrs.md: add "Extracting evolving details to living docs" paragraph after Immutability, and add review heuristic to flag evolving content added to accepted ADRs - skills/writing-adrs/SKILL.md: add "When operational details evolve" section, red flag entry, and common mistake entry Note: make lint could not run (sandbox network policy blocks pre-commit hook installation). Manual verification of lint is required. Closes #6423 --- docs/contributing/adrs.md | 4 +++- skills/writing-adrs/SKILL.md | 15 +++++++++++++++ 2 files changed, 18 insertions(+), 1 deletion(-) diff --git a/docs/contributing/adrs.md b/docs/contributing/adrs.md index e814189ce3..b14f840b86 100644 --- a/docs/contributing/adrs.md +++ b/docs/contributing/adrs.md @@ -4,6 +4,8 @@ These rules apply whenever you touch `docs/ADRs/` or review a PR that does. Full **Immutability:** Once an ADR on `main` has status **Accepted**, it is a point-in-time record. Do not substantially rewrite its Context, Decision, or Consequences sections. When circumstances change, write a **new** ADR that supersedes the old one. Minor annotations are welcome: cross-references to related ADRs, short notes linking to newer decisions, typo and broken-link fixes, and status changes (e.g., to Deprecated or Superseded). Call out any edits to accepted ADRs in the PR description. +**Extracting evolving details to living docs:** When operational details mentioned in an accepted ADR evolve over time (field tables, struct definitions, merge rules, configuration examples), do not update the ADR. Instead, extract those details to a living reference document under `docs/contributing/` and link from the ADR to the new document. The ADR records the decision; the living doc tracks the current state. See [`docs/contributing/harness-fields.md`](harness-fields.md) for a concrete example — it holds the evolving field tables while [ADR-0045](../../docs/ADRs/0045-forge-portable-harness-schema.md) records the original decision. + **New ADRs in pull requests:** Approval happens at **merge**, not when the branch is created. If the decision is made, set status to **Accepted** in the ADR you are proposing — not a lesser status merely because the PR is open. Valid statuses are **Accepted**, **Deprecated**, and **Superseded**. When status is Accepted, update `docs/architecture.md` and related problem docs in the same PR per the writing-adrs skill. When editing an ADR that has not yet merged to `main`, change the content directly — do not add "Revised" annotations, revision dates, or revision history sections. The ADR is still being authored; treat edits as normal authoring, not post-acceptance amendments. -**When reviewing PRs:** Flag substantial rewrites to Context, Decision, or Consequences on Accepted ADRs already on `main` as a policy violation. Allow minor annotations (cross-references, short notes, typo fixes), status updates, and supersession links. For brand-new ADR files on the PR branch, evaluate whether the recorded decision matches the diff — do not treat **Accepted** on a new file as a mistake if the ADR is ready for human review at merge. +**When reviewing PRs:** Flag substantial rewrites to Context, Decision, or Consequences on Accepted ADRs already on `main` as a policy violation. Allow minor annotations (cross-references, short notes, typo fixes), status updates, and supersession links. Flag PRs that add evolving operational detail (field tables, struct definitions, merge rules, configuration examples) to an accepted ADR — the correct approach is to extract those details to a living doc under `docs/contributing/` and link back. For brand-new ADR files on the PR branch, evaluate whether the recorded decision matches the diff — do not treat **Accepted** on a new file as a mistake if the ADR is ready for human review at merge. diff --git a/skills/writing-adrs/SKILL.md b/skills/writing-adrs/SKILL.md index 21ba0f3846..ba813bc553 100644 --- a/skills/writing-adrs/SKILL.md +++ b/skills/writing-adrs/SKILL.md @@ -45,6 +45,17 @@ If a decision turned out to be wrong, that is what supersession is for. The original ADR remains as a historical record of what was decided and why. For ongoing design narrative, use `docs/architecture.md`. +**When operational details evolve:** ADRs sometimes describe operational details +that change over time — field tables, struct definitions, merge rules, or +configuration examples. When those details need updating, do not modify the +ADR. Instead, extract them to a living reference document under +`docs/contributing/` and add a link from the ADR to the new document. The ADR +records the decision; the living doc tracks the current state. For example, +[`docs/contributing/harness-fields.md`](../../docs/contributing/harness-fields.md) +holds the evolving field classifications while +[ADR-0045](../../docs/ADRs/0045-forge-portable-harness-schema.md) records the +original schema decision. + ### docs/architecture.md is always current Unlike ADRs, `docs/architecture.md` is a **living document**. It must always @@ -204,6 +215,9 @@ If the ADR partially answers a question, add a parenthetical: accepted ADR -- write a new superseding ADR instead - You're turning an old ADR into a running changelog -- use `docs/architecture.md` for evolving design narrative +- You're adding evolving operational details (field tables, struct definitions, + merge rules) to an accepted ADR -- extract them to a living doc under + `docs/contributing/` and link back ## Common Mistakes @@ -219,5 +233,6 @@ If the ADR partially answers a question, add a parenthetical: | Substantially rewriting an accepted ADR | Write a new ADR that supersedes it | | Omitting cross-references to related ADRs | Link older ADRs to newer related decisions | | Treating old ADRs as evolving design docs | Use `docs/architecture.md` for living narrative | +| Adding evolving operational details to an accepted ADR | Extract to a living doc under `docs/contributing/` and link back | | Forgetting to update architecture.md | It must always reflect current decisions | | Leading zeros in title number | Use `"1. Title"` not `"0001. Title"` — zero-padded numbers are only for filenames |