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 |