SOP-022 — Maintain a foundational document

SOP · owner: Documentation (Documentarian). Layer: SOP/Runbook (docs/canon.md). Procedure for creating or revising a foundational doc under docs/ and handing it to the Archivist. Links to canon, does not restate it.

Interface Contract

Inputs: foundational document change request ← from <document owner / Principal> · trigger: “document changed”
Outputs: approved foundational document → to Archivist · trigger: “artifact approved”
Inputs: preserved record (fan-out) ← from Archivist · trigger: “preservation complete”
Handoff trigger (in): a foundational doc under docs/ must be created or revised, or an upstream doc changed and dependents need updating
Handoff trigger (out): the doc is self-reviewed, canon/glossary updated, and (for substantive change) Principal-approved
Definition of Done before handoff:
- [ ] Quality bar passed (charter “Quality bar”: falsifiable · non-redundant · resolving · glossary-aligned · canon-indexed · voice-preserving · coherent)
- [ ] Canon index (docs/canon.md) updated if the doc was added/moved (run SOP-023)
- [ ] Substantive foundational change has Principal sign-off (JD process step 1)
- [ ] Learnings captured to docs/knowledge/ if any (reported for indexing, SOP-024/025)

Purpose

Create or revise a foundational document under docs/ so it stays accurate, coherent, and cross-linked — then hand it to the Archivist for preservation. This is the unit’s core recurring procedure.

When to use

A foundational doc must be written or changed: a new cornerstone is needed; a decision changed and a doc drifted; an upstream doc emitted document changed and a dependent must be reconciled.

Flow

flowchart LR
  P["Propose<br/>(+ sign-off if<br/>substantive)"] --> D["Draft / revise<br/>in docs/"]
  D --> SR{"Self-review:<br/>quality bar?"}
  SR -->|fail| D
  SR -->|pass| CI["Canon index +<br/>glossary (SOP-023)"]
  CI --> A["Hand to Archivist<br/>'artifact approved'"]
  classDef s fill:#1d4ed8,color:#fff,stroke:#1e3a8a
  classDef g fill:#0f766e,color:#fff,stroke:#134e4a
  class P,D,CI,A s
  class SR g

Text fallback: propose the change (get Principal sign-off if substantive) → draft/revise under docs/ → self-review against the quality bar, looping until it passes → update the canon index and glossary (SOP-023) → hand to the Archivist with the trigger artifact approved.

Steps

Propose the change in one short paragraph (what + why). For substantive foundational content, get the Principal’s sign-off before writing (JD step 1).
Draft / revise the working copy under docs/, matching the doc’s existing structure and voice. For docs/concept.md, treat as protected — deliberate, approved edits only; never a silent rewrite.
Self-review against the charter quality bar: falsifiable, non-redundant (link, don’t restate), resolving cross-links, glossary-aligned, voice-preserving, coherent with CLAUDE.md/ORG.md/canon. Fix or surface any conflict.
Update the canon index + glossary (run SOP-023) if the doc was added, moved, or introduced a new load-bearing term.
Hand to the Archivist: emit artifact approved. The Archivist writes first/latest + MANIFEST and returns preservation complete.
Confirm what changed (paths, the gist of the change).

Roles / approvers

Authored by the Documentarian. Substantive foundational change is approved by the Principal (canon RACI-lite, Foundational row). Preservation is the Archivist’s (SOP-EX / SOP-002). Rule changes are not ours — propose to Golden Rule.

Guardrails

docs/concept.md is protected — approved edits only; preserve meaning.
Link to canon, never restate (CONTRIBUTING.md).
Stay in lane — do not edit archive/, CLAUDE.md, ORG.md, agent defs, or docs/handoff-triggers.md; propose to their owners.
Triggers are drawn verbatim from docs/handoff-triggers.md — never invent inline (route new ones through Operations).

See also: SOP-023 · SOP-024 · charter (docs/units/documentation/charter.md) · interface-contract-spec.md · SOP-002 (docs/sop/change-management.md).