Decision Records: Governance Memory: Difference between revisions
m →Where Decision Records Live (Hybrid Model): Updated link |
→How to Write a Decision Record: Fixed <pre><nowiki></nowiki></pre> |
||
| Line 69: | Line 69: | ||
== How to Write a Decision Record == | == How to Write a Decision Record == | ||
<pre><nowiki> | |||
=== DR-XXXX: [Short, specific title] === | === DR-XXXX: [Short, specific title] === | ||
'''Decision:''' [What was actually decided — one sentence] | '''Decision:''' [What was actually decided — one sentence] | ||
| Line 79: | Line 79: | ||
'''Date:''' YYYY-MM-DD | '''Date:''' YYYY-MM-DD | ||
'''Superseded by:''' [DR-XXXX, date — only if applicable] | '''Superseded by:''' [DR-XXXX, date — only if applicable] | ||
</nowiki></pre> | |||
'''"Open — Unresolved" is a valid, complete status''' — not every decision needs forced closure. A deliberately preserved disagreement (see the severity/disclosure tension in [[Standards Taxonomy: Calibration Decision Records]]) is a complete record on its own; the record's job is to preserve reasoning on both sides, not manufacture resolution. See [[Breadcrumb Philosophy]]. | '''"Open — Unresolved" is a valid, complete status''' — not every decision needs forced closure. A deliberately preserved disagreement (see the severity/disclosure tension in [[Standards Taxonomy: Calibration Decision Records]]) is a complete record on its own; the record's job is to preserve reasoning on both sides, not manufacture resolution. See [[Breadcrumb Philosophy]]. | ||
Revision as of 23:32, 14 July 2026
|
CYCLE Calibration position — Active Development This page is a conceptual instrument under Permanent Beta. It declares a real calibration position, not a finished product waiting to ship. Checking continues; an edit is only required when evidence demands it. Stage: Seed to Fruit. Feedback welcome — especially clarity, failure modes, and calibration gaps. Use discussion or Contribute. |
Meta
Decision Records: Governance Memory
| Type | Meta & Framework |
|---|---|
| Functional Layer | |
| Application Layer | Framework Infrastructure |
| Category | Meta & Framework |
| Version | 0.2 |
| Maturity | Development |
| Last Calibration | 2026-07-14 |
| Status | Permanent Beta |
| Description | Defines what a Decision Record is, when one is required, where it lives, and how to write one — the governance memory layer explaining why rules exist, not just what they are. |
Menu
Core Principles
- Reality gets final vote
- See the Game. Refuse the Game. Build Better.
- Permanent Beta
Navigation
Related
Decision Records: Governance Memory
Calibration Reports and Calibration Logs record how a page's content and status changed. Decision Records record why a governance rule, taxonomy category, or structural convention exists in its current form — including the alternatives that were rejected and why. The purpose of a Decision Record can be stated in one question: was this actually considered, or just never questioned? Without an answer to that question preserved somewhere, a future contributor who disagrees with a rule has no way to tell the difference.
Decision Record Principles
These are not procedures — they are the philosophy the procedures below exist to serve. A Decision Record should:
- Preserve reasoning, not advocate for it.
- Record rejected alternatives fairly enough that a future contributor can understand why they were attractive in the first place.
- Distinguish observed facts from judgment calls.
- Make later recalibration possible rather than freezing debate.
- Be concise enough that future contributors will actually read it.
A Decision Record documents governance reasoning, not objective truth. Its existence means "we know why we currently do this" — not "this debate is closed forever." Treating a Decision Record as evidence a matter can no longer be questioned would itself be a Reality Override pattern.
What a Decision Record Is
A Decision Record captures, for one specific structural decision:
- A unique ID
- What was decided
- Significant contributors to each position taken (not necessarily every participant)
- What alternatives were considered and rejected, and specifically why
- The consequences of the decision — what else it affects or requires
- Current status
- Date
When a Decision Record Is Required
Trigger test: Would a future contributor reasonably ask "why does this rule exist?" if they read only the current page, with no other context? If yes, a Decision Record is required. If the change is wording, sequencing, formatting, or a correction of an actual error, it is not.
Concretely, required when a change:
- Establishes, renames, or retires a taxonomy category or Type.
- Adopts or rejects a proposed rule, threshold, or formula.
- Resolves a genuine disagreement between contributors or reviewers, especially one where the losing position had real merit worth preserving.
- Changes a structural convention other pages are expected to follow.
Not required for: typo fixes, rewording for clarity, routine field updates, or anything already fully explained by a normal Calibration Report.
Where Decision Records Live (Hybrid Model)
1. Central Index — Decision Records: Governance Memory/Index A single, chronological, scannable list of every Decision Record, by ID. Each entry: ID, date, short title, page(s) concerned, link to full record. Browsing/search only — never long-form content.
2. Per-Page Subpages — `PageName/Decision Records` (naming locked: matches `/Calibration Log` convention exactly) Full content lives on a subpage attached to the governance page it primarily concerns.
For decisions spanning multiple pages: the record lives on whichever page is most directly responsible for enforcing the decision, with a cross-reference added to other pages involved, and the Index entry notes all affected pages.
ID Format
Every Decision Record receives a sequential ID: DR-0001, DR-0002, DR-0003..., assigned in the order created, never reused even if a record is later superseded or rejected. Pages may reference a decision by ID alone (e.g. "see DR-0004") once the record exists, rather than restating its full title.
How to Write a Decision Record
=== DR-XXXX: [Short, specific title] === '''Decision:''' [What was actually decided — one sentence] '''Status:''' Proposed / Adopted / Superseded / Rejected / Open — Unresolved '''Significant contributors:''' [Major positions and who held them — not necessarily every participant] '''Reasoning:''' [Why the adopted position won] '''Alternatives considered:''' [What else was proposed, and specifically why it was set aside] '''Consequences:''' [What this decision requires or affects elsewhere — other pages, future conventions, follow-up work] '''Date:''' YYYY-MM-DD '''Superseded by:''' [DR-XXXX, date — only if applicable]
"Open — Unresolved" is a valid, complete status — not every decision needs forced closure. A deliberately preserved disagreement (see the severity/disclosure tension in Standards Taxonomy: Calibration Decision Records) is a complete record on its own; the record's job is to preserve reasoning on both sides, not manufacture resolution. See Breadcrumb Philosophy.
Superseding a Decision Record: never delete or overwrite a superseded record's content. Mark its status "Superseded," add the superseding record's ID and date, and leave the original content fully intact as historical record — consistent with the append-only principle used throughout this project (Talk page Calibration Reports, page history).
Relationship to Other Mechanisms
| Mechanism | Question Answered |
|---|---|
| Versioning | When did it change? |
| Calibration Report | How did it change? |
| Calibration Log | What's its current calibration state? |
| Decision Record | Why does this rule exist? |
| Breadcrumb | What is still unresolved? |
Decision Records are historical, like Calibration Reports — but narrower: a Calibration Report documents one review pass on one page; a Decision Record documents one structural decision, possibly debated across multiple passes, pages, or contributors before resolving (or deliberately not resolving).
Worked Precedent
Standards Taxonomy: Calibration Decision Records predates this page and should be treated as the de facto first per-page Decision Records subpage — retroactively conforming to this standard (adding IDs, Consequences fields, and updated Status values) is a follow-up task, not required immediately.
Calibration Dependencies
- Breadcrumb Philosophy
- Standards Taxonomy: Calibration Decision Records
- Calibration Log: When to Create One
Open Items
- Decision Records: Index does not yet exist — high priority, treat as needing to exist alongside this page rather than deferred. (Trigger breadcrumb: resolved once the Index page exists and contains at least the Standards taxonomy decisions, retroactively assigned IDs.)
- Dependency between Decision Records (Decision A creates Decision B; B later makes A obsolete) is not yet addressed structurally — flagged by round-robin as a future challenge, not solved now. The "Superseded by" field handles simple linear supersession; a decision that depends on or was enabled by another (without superseding it) has no stated mechanism yet.
- Retrofitting Standards Taxonomy: Calibration Decision Records to add IDs and Consequences fields is a follow-up task, not yet done.
See the Game. Refuse the Game. Build Better.