Advisory Brief — Org-Wide Self-Documentation Program

From: External Review Partners (retained independent advisor) To: The Principal — feeding the COO, who authors the actual plan Date: 2026-06-01 · Kind: advisory (pre-plan input) Status: independent advisory only. ERP is read-only on the org; this is the one file we wrote. We did not draft the program plan — that is the COO’s. 2026-06-01 addendum: the Principal added knowledge management to scope. Section 9 covers it; the verdict (sec. 10) is re-issued to fold it in.

0. Bottom line up front

The mandate is sound and overdue: 43 agents, each with a JD, but no agent-level documentation below the JD and no machine-checkable map of where one agent’s work ends and the next begins. The existing canon hierarchy (macro → job aid) and the templates/ set are good bones — you do not need new doctrine, you need fill, a handoff contract, and an integrity check. The single biggest risk is theater: 43 agents producing 200+ plausible documents that no one can prove are complete, non-overlapping, or current. Defeating that risk is the whole game. Two recommendations matter most: (1) make every agent’s docs derive from, not duplicate, the canon — one home per fact; (2) mandate a single Interface Contract block in every agent’s SOP set plus an org-wide Handoff Register that is mechanically reconciled. Without (2), “seamless handoffs” is a slogan.

Overall readiness for this program: MODERATE. Scaffolding exists; the governance to prevent drift and prove completeness does not yet.

1. Framing & success definition

“Done” is not “every agent wrote some docs.” Define done on three axes and refuse to declare victory unless all three pass:

• Coverage — every agent owns the required artifact set (sec. 2), every artifact slot filled or explicitly marked N/A — <reason>. Empty ≠ done; an honest N/A is done.
• Integrity (handoffs) — every declared output has a named downstream consumer and every declared input a named upstream producer; the org-wide Handoff Register reconciles to zero unmatched edges (sec. 3).
• Coherence — no fact has two homes; cross-links resolve; terminology matches docs/glossary.md; nothing contradicts CLAUDE.md, ORG.md, or canon.

The quality bar — “genuinely complete vs. theater.” A documentation set is real, not theater, when it survives four tests:

1. Executable — a competent stranger (or a fresh agent instance) could do the job from the job aids without asking the incumbent. This is the acid test for the lowest altitude.
2. Non-redundant — it links to canon rather than restating it. Restated content is the #1 source of future drift; treat copy-paste of CLAUDE.md/policy text as a defect, not coverage.
3. Falsifiable — claims are specific enough to be wrong (named files, exact triggers, exact commands), not mood music (“collaborate closely”).
4. Interlocking — its inputs/outputs name real counterparties who agree they are the counterparty.

A document that reads well but fails #1 or #4 is the failure mode to hunt for.

2. Recommended structure — the artifact set every agent owns

Map agent artifacts onto the existing canon layers; do not invent a parallel hierarchy. The altitude range the mandate asks for already exists in docs/canon.md (macro → foundational → policy/process → SOP/runbook → job aid). The gap is that today only the JD and a handful of org-wide SOPs/job-aids exist; per-agent depth below the JD is missing.

Required set, per altitude:

Where unit-level vs. agent-level sits. Charters and the operating model are unit-level and owned by the Lead — do not have three Engineering members each write a competing charter. SOPs and job aids are agent-level and owned by the individual. This split is the cleanest defense against duplication: macro/ foundational content converges upward to one unit owner; procedural detail stays distributed. The JD already exists and is governed by hr/policies/job-descriptions.md — do not rewrite JDs in this program; treat them as the fixed apex and document downward from them.

Caveat — right-size by role. A solo-unit Director (e.g. Golden Rule, Quality & Risk, Product Manager) does not need a unit charter and a role manual and five SOPs; for many roles charter+manual collapse into one doc and 1–3 SOPs suffice. Mandating a fixed document count per agent is itself a path to theater (GR-4 — analyze the need before you build). The COO should set a minimum (JD + one charter/manual + at least one SOP + at least one job aid for any agent that performs a recurring procedure) and let need drive the rest.

3. The seamless-handoff standard (the load-bearing recommendation)

This is where the existing scaffolding is insufficient and where the program will live or die. The org has rich prose about who-collaborates-with-whom (Collaborators lines in JDs) but nothing machine-checkable that proves there are no gaps or overlaps. Recommend two artifacts:

(a) Interface Contract block — a fixed, parseable block at the top of every agent SOP. Proposed shape:

## Interface Contract
- Inputs:   <artifact> ← from <upstream agent/unit> · trigger: <exact event>
- Outputs:  <artifact> → to <downstream agent/unit> · trigger: <exact event>
- Handoff trigger (in):  <the precise condition that starts my work>
- Handoff trigger (out): <the precise condition that ends my work and starts theirs>
- Definition of Done before handoff: <checklist>

The discipline is that a handoff is named on both sides and uses the same trigger phrasing. If my “out” trigger to the Archivist does not match the Archivist’s “in” trigger from me, that is a defect the register will catch.

(b) Org-wide Handoff Register — a single matrix (one row per declared edge: producer → artifact → consumer → trigger) aggregated from all Interface Contracts. Recommend it live as a foundational doc (Operations owns the mechanism; the Archivist preserves it). Proof of no-gaps/no-overlaps = reconciliation:

• Every output edge must match exactly one input edge on the consumer’s side (and vice versa). Unmatched output = a dropped handoff (gap). Unmatched input = a dangling dependency (gap). Two producers claiming the same output artifact = an overlap (ownership conflict — escalate to canon RACI).
• The reconciliation should be a script, not a human eyeball (GR-2 — prefer native Claude Code / automation). A simple parser over the Interface Contract blocks, run as a hook or CI check, turns “seamless handoffs” from aspiration into a green/red gate. This is the single highest-leverage build in the program.

Without (b), Phase 2 “converge as one unit” has no objective stopping condition and will degrade into 43 agents asserting their own seams are fine.

4. Sequencing — waving 43 agents through Phase 1 → Phase 2

Do not start all 43 in parallel cold; you will get 43 incompatible formats. Sequence to establish the pattern, then scale:

• Wave 0 — Pattern & pilot (before anyone else drafts). Operations + the Documentarian finalize: the Interface Contract block, the Handoff Register format, and the reconciliation check. Then 2–3 pilot agents that sit on a known seam draft their full set end-to-end — recommend Archivist + Documentarian + one Engineering member, because they exercise the macro→job-aid range and a real handoff (authoring → preservation). Freeze the exemplar from the pilot; it becomes the gold standard every later wave copies. This de-risks format drift cheaply.
• Wave 1 — Foundational/governance cluster (Archives, Rules & Governance, HR, Documentation, Finance, Legal). These own the canon, templates, RACI, and archive flow that everyone else references. Their docs must be stable first or downstream agents will cross-link to moving targets.
• Waves 2–4 — by cluster (CPTO, COO, CGEO), each cluster as a batch so the C-suite head can enforce internal consistency before cross-cluster convergence.
• Within each wave, Leads draft before members. The unit charter (Lead-owned) sets the boundary the members’ SOPs must fit inside. Members drafting first invites overlap.

Dependency rule: an agent cannot complete Phase 1 until every counterparty it names in an Interface Contract at least exists as a stub. Stub-first (declare your edges) → fill → reconcile.

Phase 2 (“as one unit”). This is not a free-for-all editing session; it is a reconciliation pass driven by the Handoff Register and a de-dup sweep:

1. Run the register reconciliation; produce the defect list (gaps/overlaps).
2. Resolve each defect at the correct altitude — overlaps in ownership go to canon RACI (sec. 5), not to negotiated prose between two agents.
3. De-dup sweep: any restated canon content is replaced with a link (one home per fact). 4. Cross-link pass. 5. Glossary alignment. 6. Final reconciliation = green.

5. Governance & ownership

Reuse the existing RACI in docs/canon.md rather than inventing a new one — that table already names Author/Approve/Archive/Cadence per doc class:

• SOP / job aid → authored by the owner (agent), approved by the owner’s Director, archived by the Archivist, reviewed quarterly. This already covers the bulk of the new corpus.
• Unit charter / role manual → treat as foundational/operating-model class: authored by the Lead, approved by the cluster C-suite head (or Principal for direct-report units), archived by the Archivist.
• Handoff Register → recommend Operations owns the mechanism and reconciliation; Quality & Risk provides independent assurance it stays green (this is squarely Q&R’s “second line of defense” mandate — use it). Approval of the program completion sits with the COO (program owner) reporting to the Principal.
• Program orchestration → the COO owns the plan; recommend the Project Manager (Delivery/PMO) runs the wave schedule and tracks completion per agent. This is exactly PMO’s charter — do not create a new coordinator.

Preservation flow: every artifact, on approval, hands to the Archivist per the standing omni-intake; scripts/archive-manifest.sh must show 0 drift as part of each artifact’s Definition of Done (mirror SOP-002’s DoD). Do not let this program bypass the archive flow — that is how the record rots.

Staleness defense: every new doc carries last-reviewed: + owner (already the canon convention) and is swept by the operating-cadence staleness sweep. Add the Handoff Register reconciliation to the session-close / CI checks so a broken seam surfaces within a day, not a quarter. NOTE: the automated cadence is currently a no-op (operating-cadence is “NOT YET ACTIVE” pending AR-003 secrets) — so the staleness sweep is presently manual. Flag this to the Principal: the program’s anti-staleness mechanism depends on infrastructure that is not wired. Either wire it or assign the manual sweep explicitly; do not assume it runs.

6. Risks & failure modes (adversarial)

7. Success metrics

• Coverage % = (filled-or-justified artifact slots) ÷ (required slots), per agent and org-wide. Target 100% with explicit N/A allowed. Empty slots do not count as covered.
• Handoff integrity = unmatched edges in the Handoff Register. Target: 0. This is the headline metric; report it as a single red/green number.
• Redundancy defects = count of restated-canon passages found in the de-dup sweep. Trend to 0; a rising count means the corpus is drifting toward theater.
• Executability pass rate = % of sampled job aids that pass the stranger-can-do-it review (Q&R-run, stratified sample). Target ≥ 90%.
• Freshness = % of docs within their review cadence (no overdue last-reviewed:). Watch this after launch — it is the staleness early warning.
• Archive integrity = archive-manifest.sh drift. Target: 0, continuously.

8. Verdict (documentation program)

Proceed — the mandate is correct and the org has the bones. But fund the plumbing before the volume: the Interface Contract, the Handoff Register, and a scripted reconciliation gate are the difference between a coherent corpus and 200 documents of plausible noise. Sequence through a frozen pilot exemplar; converge in Phase 2 against the register, not against opinion; resolve overlaps at canon RACI; and do not declare done until handoff integrity reads zero. Two existing weaknesses to fix in-flight: the staleness-sweep automation is a no-op (AR-003), and the roster carries stale references (innovation-lead, CIA reports-to) that would produce phantom handoffs. Clean those before Wave 1.

9. Knowledge management (added to scope 2026-06-01)

The documentation program above hardens how-it-works (durable, structural). Knowledge management is the other half of the same coin: how-we-got-smarter (accruing, dated, hard-won). The Principal is right to scope it now — without it, the doc program produces a static snapshot that decays, and the org’s most valuable asset (what 43 experts learn by doing) evaporates at every session reset.

Readiness for KM specifically: LOW–MODERATE. The intent is well-formed — docs/knowledge/ exists with a clear charter, GR-6 mandates capture at close, and every JD’s Expertise field obliges each agent to “stay current and capture learnings.” But the mechanism is thin: three knowledge entries exist for a 43-agent org that has run multiple staffing rounds and shipped a product slice; there is no knowledge template, no per-unit playbook anywhere, and the only capture trigger (GR-6) rides on the same session-close cadence that is a no-op today (AR-003). KM is currently aspiration backed by one good README.

9.1 The seam: documentation vs. knowledge (and why both, without duplication)

These are different kinds of writing and must not bleed into each other — the single most common KM failure in document-heavy orgs is letting the two collapse, producing knowledge bases full of restated procedure and SOPs polluted with war-stories.

The clean rule — and the seam between them: a learning is captured in docs/knowledge/ first (cheap, dated, append-only); when a learning proves durable, it is promoted into the documentation corpus and the knowledge entry links to its new home. The knowledge entry’s “Next time” bullet is the trigger: if “next time” is now permanent practice, it belongs in an SOP/job-aid/manual, not only in a dated note. This makes the two non-duplicative by construction — knowledge is the inbox, documentation is the system of record, and the link between them prevents the same fact living in both. The existing entry 2026-05-30-intranet-and-archive-automation.md already models this informally (its “Next time” points at reusing sync-content.mjs); formalize it as the rule.

How each agent contributes to both without overlap: every agent already owns documentation downward from its JD (sec. 2). For knowledge, every agent is a contributor but not an owner — they file dated entries against the topics they worked; the three named owners curate, process, and preserve. This mirrors the archive’s omni-intake: distributed capture, centralized curation. No agent owns a slice of docs/knowledge/; that is correct and should stay that way, or you recreate the turf problem the doc program is trying to kill.

9.2 The capture lifecycle every agent follows

KM is only real if it is a cadence, not a virtue. Recommend a five-stage lifecycle, explicitly tied to the two-phase model and the handoff standard:

CAPTURE → CURATE → PRESERVE → INDEX → RETRIEVE
(agent)   (Documentarian) (Archivist) (Documentarian) (every agent, daily)

1. Capture (every agent, at the moment of learning and at session close). When an agent hits a non-obvious result — a gotcha, a dead end, a pattern that worked, a calibration number — it drafts a knowledge entry or appends to one. GR-6 makes this mandatory at session close; do not let it be only at close, or you lose the mid-session detail. Tie to the handoff standard: a knowledge entry is a legitimate part of an agent’s Definition of Done before handoff — the Interface Contract’s DoD checklist (sec. 3) should include “learnings captured” for any task that produced one. This is how KM rides the same rails as the doc program rather than being a separate ritual nobody does.
2. Curate (Documentarian, weekly + at session close). Triage new entries: dedupe, merge same-topic notes, fix the title to the YYYY-MM-DD-<slug> convention, and decide promotion — does this learning now belong in the documentation corpus? Curate is where sprawl is prevented; an uncurated knowledge base is a junk drawer within a quarter.
3. Preserve (Archivist, on entry/approval). Standard omni-intake: first/latest versioning + MANIFEST + archive-manifest.sh 0-drift. Knowledge entries are append-only, so preservation is cheap and the “nothing is lost on reset” guarantee is real — provided the entry was actually written.
4. Index (Documentarian, on every add). Two indices must update together: the table in docs/knowledge/README.md and the Knowledge row in docs/canon.md. Today the README index lists only one of the three existing entries (the ai-systems-retrieval-review and the unit-research library entries are not in it) — a small but telling sign the index is already drifting from the directory.
5. Retrieve (every agent, at session open). The Perfect-Employee standard says review canon each morning; extend that explicitly to the Knowledge Base index so an agent picks up where the org left off, not where its own context window starts. This closes the loop on session reset (sec. 9.5).

Tie to the two-phase doc program: run KM as a thin parallel track, not a third phase. In Phase 1, each piloting agent files at least one real knowledge entry so the template and cadence are exercised alongside the doc set. In Phase 2, the de-dup sweep gains a KM step: any knowledge “Next time” that has become standing practice is promoted into the corpus and the entry linked — this is the moment knowledge and documentation are reconciled against each other.

9.3 Discoverability, retrieval, and anti-staleness

• Two-index discipline. A knowledge entry does not exist until it is in both docs/knowledge/README.md and the canon Knowledge row. Recommend a scripted check (GR-2) that fails if a docs/knowledge/*.md file is absent from the README index — the same mechanical-reconciliation philosophy as the Handoff Register. Manual indices always drift; this one already has.
• Promotion link as the retrieval shortcut. Because durable learnings get promoted into SOPs/manuals, the primary retrieval surface for an agent doing the work is the documentation corpus (always-current), and docs/knowledge/ is the deeper archive of why and what-was-tried. An agent should not have to read 200 dated notes to do its job — it reads canon; it consults knowledge when it needs the history or hits a novel problem.
• Anti-staleness for knowledge is different from documentation. Knowledge entries are dated records — they do not go stale the way a procedure does; an old learning is still a true record of what was learned then. So do not apply a last-reviewed: expiry to knowledge entries (that would invite pointless churn). Instead the freshness control is supersession: when a later learning contradicts an earlier one, the new entry references and supersedes the old, and curation flags the old entry as superseded rather than editing history. The staleness risk that is real is in the promoted content (now living in SOPs) — that is covered by the existing last-reviewed: sweep. Net: knowledge is governed by supersession, documentation by expiry. Keep them distinct.

9.4 Per-unit playbooks (the knowledge analogue to per-agent job aids)

The doc program’s lowest altitude is the per-agent job aid (“do this exactly”). Its knowledge analogue is the per-unit playbook (“here’s what we’ve learned works in this domain”). The Knowledge Base README already anticipates this — “Units may keep a playbook of accumulated know-how for their domain” — but zero playbooks exist. Recommend:

• One playbook per unit, owned by the Lead (mirrors the unit-charter ownership in sec. 2 — converges upward, no per-member competition). It is a living digest of the unit’s durable know-how: recurring patterns, named failure modes, hard numbers (e.g. the AI Systems retrieval thresholds, the chunk-count ceilings), the “demons” the concept itself calls for naming.
• Sourced from, not duplicative of, knowledge entries. A playbook is the curated, deduped, promoted layer that sits above raw dated entries — the unit’s greatest hits, cross-linked to the entries and SOPs they came from. This keeps it from becoming a fourth copy of the same fact.
• Right-size it (GR-4). A solo unit may keep a single-page playbook or fold it into its role manual; do not mandate a heavy playbook for every unit on day one. Seed playbooks in the units that have already generated real learnings (Archives, Engineering, AI Systems, Operations, Design Research) and let the rest follow as knowledge accrues.

9.5 KM-specific risks and mitigations

9.6 KM recommendations (prioritized)

1. Ship the missing primitives first (cheap, high leverage): a templates/knowledge-entry.md, a templates/playbook.md, and a scripted two-index reconciliation check. Without these, scaling capture to 43 agents reproduces the doc program’s format-drift and orphaning risks in a second corpus.
2. Bind capture to the handoff DoD, not only to session close — because the close-cadence automation is a no-op today (AR-003), a capture trigger that lives only there does not fire. This is the same flag raised in sec. 5, and it bites KM harder than it bites documentation.
3. Add a session-open retrieval step (read the Knowledge index) to the Perfect-Employee morning routine, so session reset stops being a memory wipe.
4. Seed 4–5 unit playbooks from units that already have real learnings; let the rest accrue. Do not mandate 21 playbooks on day one (GR-4).
5. Make curation a named, cadenced job for the Documentarian, with Q&R sampling promotion/indexing — KM dies quietly when “everyone curates,” i.e. no one does.

10. Verdict (re-issued, both halves)

Documentation program: proceed — fund the plumbing (Interface Contract, Handoff Register, scripted reconciliation) before the volume; converge in Phase 2 against the register, not opinion; do not declare done until handoff integrity reads zero. Clean the roster hygiene and the staleness no-op before Wave 1.

Knowledge management: proceed, but treat it as under-built, not done. The charter and intent are sound; the mechanism is three entries, no template, no playbooks, and a capture trigger riding a dormant cadence. The discriminating moves are (1) the promote-and-link seam that keeps knowledge and documentation non-duplicative, (2) capture bound to the handoff DoD so learnings survive session reset, and (3) named, cadenced curation with mechanical indexing so the base doesn’t sprawl or orphan. Knowledge is governed by supersession, documentation by expiry — keep the two governance models distinct. Run KM as a thin parallel track inside the same two-phase program; do not bolt it on afterward.

— External Review Partners. Independent; read-only on the org. Hand to the Archivist for preservation.