`/knowledge/decisions/`¶

Structured records of significant decisions — technical, architectural, operational, or strategic — so future readers and agents understand WHY things are the way they are, not just WHAT they are.

What is a decision record?¶

A decision record (sometimes called an ADR — Architecture Decision Record — in software engineering teams) is a short structured document that captures:

Context — what situation prompted the decision
Decision — what was actually chosen
Alternatives considered — other options and why they were rejected
Consequences — what this commits the organization to, including trade-offs
Stakeholders and date

Why we keep them¶

Decisions made today inform the work done tomorrow. Six months from now, a future team member (or agent) will encounter something done a specific way and want to know WHY. A decision record answers that in 2 minutes. Without it, the question gets relitigated — or worse, the decision gets unconsciously reversed because nobody remembers the reasoning.

Keeping decision records: - Prevents relitigation - Preserves institutional memory as the team scales - Makes onboarding dramatically faster for future hires or agents - Lets chief.staff's audit trail be coherent across time - Links cause (decision) to effect (SOP, code, architecture)

When to file one¶

File a decision record for:

Architectural choices — what platform, what pattern, what structure. Example: "Missions = Epics, not Roadmap items."
Tool selection — when multiple tools could do the job and you picked one. Example: "Obsidian as primary wiki, Notion for 4 narrow exceptions only."
Governance changes affecting multiple agents. Example: "Per-agent cwd for memory namespace isolation."
Trade-off choices where both options were viable and the alternative may come up again. Example: "Bulk memory migration vs. per-file classification at agent kickoff."
Scope boundaries — what's in, what's out, what we're deliberately NOT doing.

You do NOT need a decision record for: - Routine operational calls (who posts to Slack when) - Implementation details that follow from an already-recorded decision - Things fully specified by a higher-level rule (CLAUDE.md, an existing SOP, a prior decision record)

Frontmatter convention¶

---
title: "DR-{NNN}: {Short decision summary}"
type: decision-record
status: {proposed | accepted | superseded | deprecated}
date: YYYY-MM-DD
author: {agent_id or CEO}
stakeholders: [agent_id, agent_id, ...]
supersedes: # optional: path to another DR this replaces
related_sops: []  # paths to SOPs implementing this decision
related_contracts: []  # paths to agent contracts affected
tags: []
---

Numbering¶

Decisions are numbered sequentially: DR-001-{short-slug}.md, DR-002-{short-slug}.md, and so on. chief.staff maintains INDEX.md as the master list.

Page structure¶

# DR-{NNN}: {Decision title}

## Status
{proposed | accepted | superseded | deprecated}

## Context
_What situation prompted this decision? What constraints or forces applied? What were we trying to accomplish?_

## Decision
_What did we choose? State it clearly in one paragraph or bullet list._

## Alternatives considered
_What other options were on the table, and why did we reject each? Be honest — future readers need to understand the trade-offs, not just the winner._

### Option A — {name}
_Description, pros, cons, why rejected._

### Option B — {name}
_Description, pros, cons, why rejected._

### Option C — {name}
_Description, pros, cons, why rejected._

## Consequences
_What does this decision commit us to? What becomes easier? What becomes harder? What trade-offs did we accept?_

## Related
_Wikilinks to SOPs, agent contracts, playbooks, best practices, or other decision records affected by or affecting this one._

---
**Date:** YYYY-MM-DD · **Author:** {agent_id} · **Stakeholders:** [list]

Relationship to SOPs and governance¶

CLAUDE.md — the constitution
Decision records — the reasoning behind individual choices (the WHY)
SOPs — the procedures that implement governance (the HOW)
Best practices — recurring patterns (the WHAT)

A decision record may drive changes to CLAUDE.md, SOPs, or agent contracts. Those downstream artifacts link back to the decision record that justified them.

Example decisions already made in the system¶

Pending backfill — chief.staff will retroactively file decision records for:

DR-001: Obsidian as primary wiki; Notion only for 4 narrow exceptions (decided 2026-04-14)
DR-002: Per-agent cwd for memory namespace isolation (decided 2026-04-14)
DR-003: Missions = Epics with sub-items interpretation (Option D — worker Features as Tasks via epic_tasks, governance events as files) (decided 2026-04-14)
DR-004: 7-day cadence with compressed weekend window (decided 2026-04-13 evening, v1.2.1)
DR-005: 21-agent compressed roster from 40-agent production (decided 2026-04-13)

These backfills preserve the reasoning behind choices already baked into the system.

Dashboard¶

Live index at /dashboards/decisions-log.md — sortable by date, filterable by status, grouped by category.

/knowledge/decisions/¶