Organizational Decision Record (ODR)

# Organizational Decision Record (ODR)

An **`organizational-decision-record`** — an **Organizational Decision Record (ODR)** —
is the org-design analogue of an Architecture Decision Record (ADR). It captures a
single org-design decision: what was decided, why, and the consequences expected.
Minimal by design.

It is the **decided** member of the [change](README.md) category — the decision one
step past a `proposal`, and the point from which agreements follow:

```
signal  →  insight  →  driver  →  proposal  →  ODR  →  agreement(s)
(data)     (meaning)   (motive)   (response)  (decided)  (operational)
```

That is the same chain the [category page](README.md) draws, and it is the same one
the [in-flux types page](in-flux.md) draws. The ODR is **not** the terminal box:
where the four [in-flux types](in-flux.md) make the design conversation visible, the
ODR records its **outcome**, and the `agreement`s that carry that decision out are a
further rung. It reads as a **weightier artifact** than an in-flux sensing-pin: a
recorded decision, not an annotation.

> **"Organizational" is a threshold, not decoration.** Plenty gets decided about a
> product, a tool or a team's own practice, and none of that is an ODR. The
> qualifier sits in the type key precisely because that is what an author types when
> creating one — it is the moment the question *"is this really an organizational
> decision?"* is worth asking. The drawer bucket and the filter row carry the full
> qualifier too: **Organizational Decision Records** in the drawer, **Organizational
> decision records** in the filter menu (the short label *Decision Records* is
> retired).

This document is **vendored** into the repo (from the external `dwsd-markdown`
convention spec) so that downstream work is not path-dependent on the external
`W:\` source. It is the in-repo source of truth for the
`organizational-decision-record` type model.

## Identity

| Type | `type` | Category | Anchor field | Render scope (v1) | Drawer bucket |
|---|---|---|---|---|---|
| **Organizational Decision Record** | `organizational-decision-record` | `change` | `for-domain` / `for_domain` | Topology work-system node (domain-level) | **Organizational Decision Records** |

`organizational-decision-record` is a **single** type, so it is its own top-level
drawer bucket labeled **"Organizational Decision Records"** (like "Agreements" / "Interactions" /
"AI Agents"), sorted after the existing buckets — it is *not* a super-group band,
which is the pattern for the four-type [in-flux](in-flux.md) family. In the preview's
filter menu it is the **Organizational decision records** layer (key `decision-records`,
unchanged, so stored filter state keeps working), sitting next to
*Change conversation*: the conversation ends where a decision is recorded.

## Frontmatter

| Field | Required | Format | Meaning |
|---|---|---|---|
| `type` | yes | `organizational-decision-record` | Entity type |
| `for-domain` / `for_domain` | no | wikilink | The domain / work system the decision concerns |
| `status` | no | `proposed` \| `accepted` \| `superseded` \| `deprecated` | Lifecycle of the decision |
| `date` | no | date | When the decision was recorded / last updated |
| `decision-makers` | no | wikilink or list | Who made the decision |
| `derived-from` | no | wikilink | The `proposal` / `driver` this record captures — the [shared emergence key](README.md#derived-from--the-shared-emergence-key), **metadata only** (see below) |

## Body

| Section | Holds |
|---|---|
| `## Context` | The situation and forces — why a decision was needed |
| `## Decision` | What was decided, and what we will do |
| `## Consequences` | What we expect to follow — benefits and trade-offs |

The shape is modeled on the ADR (Michael Nygard) minimal form —
Status / Context / Decision / Consequences — and is kept minimal on purpose.

## Minimal form

The minimal `organizational-decision-record` is exactly the Nygard-ADR shape: a `status` in the
frontmatter plus the three body sections. This is the spec's worked
3P/4P-merge example, verbatim:

```markdown
---
type: organizational-decision-record
for-domain: "[[Strategic Direction]]"
status: accepted
date: "2026-05-11"
decision-makers:
  - "[[COO]]"
---
## Context
The 3P and 4P work systems duplicate coordination and compete for the same teams; standard
production keeps stalling.

## Decision
Merge 3P and 4P into one FL2 work system; retire the separate 4P coordination.

## Consequences
Fewer hand-offs and one priority queue (benefit); a larger coordination scope for the
merged work system, watched via lead-time metrics (trade-off).
```

That is the whole minimal type. There is no template system and no authoring
command — a `organizational-decision-record` is authored by hand, exactly like every other
documented type: create a Markdown file with the frontmatter above and the three
body sections.

### Richer form (optional)

Two optional additions extend the minimal form for teams that want them. Both are
**optional** and are **NOT** part of the canonical `dwsd-markdown` spec — they are
documented here as the "richer" end of the minimal-and-rich range:

- **`review-by`** — a date in the frontmatter marking when the decision should be
  revisited (a review horizon for a decision expected to age).
- **`## Alternatives`** — an extra body section listing the options that were
  considered and rejected, with the reason each was set aside (the MADR-lineage
  "considered options" idea).

```markdown
---
type: organizational-decision-record
for-domain: "[[Strategic Direction]]"
status: accepted
date: "2026-05-11"
review-by: "2026-11-11"
decision-makers:
  - "[[COO]]"
---
## Context
…

## Decision
…

## Alternatives
- Keep 3P and 4P separate with a shared coordination role — rejected: does not remove the duplicate queue.
- Merge into an FL3 portfolio system — rejected: over-scopes the change for the current need.

## Consequences
…
```

Everything beyond `status` + `## Context` / `## Decision` / `## Consequences` is
optional; a `organizational-decision-record` is valid with the minimal form alone.

## Anchoring and render scope (v1)

A `organizational-decision-record` anchors **domain-level** via `for-domain` / `for_domain`,
pointing **up** at the work system (domain) the decision concerns — reusing the
`driver` / `proposal` mechanism (the `forDomainReverse` reverse-index) verbatim.
It adds no new index and no locator/grammar work. `for-domain` stays
**non-polymorphic** — it names a work system, never a board or route position.

In v1 the ODR renders as a **distinct decision-record marker** on the target
**work-system node in the topology preview** — the same domain-level precedent as
`driver` / `proposal`. It is deliberately weightier than an in-flux pin and
distinct from the FL-tinted interaction / agreement / ai-agent marker row.

**Board and route position-precise ODR rendering is deferred to v2** — it would
replicate the value-polymorphic locator work, and is out of scope for the
domain-level v1.

## `status` is drawer-content-only

The marker looks the same regardless of `status` — `proposed`, `accepted`,
`superseded`, or `deprecated`. The status is surfaced in the **drawer content
only**; there is no superseded / deprecated fade or strike on the marker in v1.
This mirrors the in-flux family's drawer-content treatment and keeps the
render near-free.

## `derived-from` is metadata-only — and it is what makes the bundle readable

An `organizational-decision-record` may be `derived-from` the
[`proposal`](in-flux.md) or [`driver`](in-flux.md) it records. That links the record
back **down** the chain. The parser has **no `derived-from` relationship type**, so it
is preserved as **metadata only** — it is *not* a second anchor and *not* a typed
graph edge, and it does not resolve to its own marker.

`derived-from` is **not a field of this type**. It is the
[shared emergence key](README.md#derived-from--the-shared-emergence-key), documented
once for every entity that can carry lineage — including the `agreement`. That is
what makes a decision's **bundle** expressible without any bundle field: the
agreements belonging to one ODR are exactly those whose `derived-from` names it. Read
backwards ("what did this come from?") the key sits in the document; read forwards
("what came of this decision?") it needs a reverse index, which is not built today.

### Where each one is pinned

An ODR is pinned at the **domain** — `for-domain`, the work system the decision
concerns. Its agreements are pinned **where the work happens** — `agreement-of`, a
board position. One decision up at the system, its consequences down in the flow.
That asymmetry is why `for-domain` here stays non-polymorphic while an agreement's
anchor is a full board locator, and why an ODR and an agreement are **different
rungs** rather than the same rung about different subjects.

## See also

- [Change entities](README.md) — the category page: the full chain, the two MADE
  phases it spans, and `derived-from` as the shared emergence key.
- [In-flux types](in-flux.md) — the `signal` / `insight` / `driver` / `proposal`
  types that lead up the chain to a recorded decision.
- [`types/…`](../) — the marker entity types (`agreement`, `interaction`,
  `ai-agent`).
- [Locator grammar](../locator-grammar.md) — the shared locator string family
  (the `for-domain` value form).