Doc taxonomy audit — do we need whitepaper, research, proposal, and user-story?
TL;DR. Four folder-types (whitepapers / research / proposals / user-stories) is close to right for what rig-docs is today, but the boundary between whitepaper and the schema-blessed types is undefined, 22 of 22 whitepapers declare type: reference in frontmatter (so the folder name is the only taxonomy signal), and the schema already allows two types the rig does not yet use (decision, runbook). Recommendation: C. Add types, sharpen boundaries, do not consolidate. Keep the four folders. Split whitepapers into foundational (evergreen — 20 files) and snapshot (dated — 2 files) genres to stop mixing audiences. Promote decisions/ (ADR-style) to a first-class folder, activate the schema latent runbook type when there is content for it, and add postmortem to the schema so post-incident learnings have a home. This mirrors how Diátaxis separates by purpose, not artifact, and adopts the Nygard ADR pattern and Google / Etsy postmortem practice without inventing anything novel.
Why this audit
Section titled “Why this audit”rig-docs started as a three-bucket system (research → proposal → user story) mirroring the way a decision travels from question to ship plan to backlog item. Whitepapers arrived later as a home for the diagram-heavy leadership-facing syntheses. At roughly 50 typed files across four folders, the system is producing three frictions:
- Whitepapers overload a single folder with two genres. memory.md, safety.md, security.md, trust-model.md are evergreen foundation (updated in place, read top-to-bottom like a book). 2026-04-19-brain-and-memory.md and 2026-04-20-whats-next.md are dated leadership snapshots that a newer snapshot eventually supersedes. The folder mixes these without signalling the difference to readers or to the RelatedDocs component.
- The frontmatter schema is ahead of folder convention. src/content.config.ts allows type in {research, proposal, decision, reference, user-story, runbook} — six types. The folder layout uses four. decision and runbook have schema seats but no folder seats. Every whitepaper declares type: reference rather than a whitepaper type (the schema does not offer one). So the folder name and the frontmatter type disagree for 22 files.
- ADR-like decisions have no home. proposals/2026-04-18-docs-tooling-decision.md is an ADR in all but name. So is whitepapers/tool-choices.md (explicitly titled An ADR for Every Pick). The rig makes decisions; it has nowhere to record them that is neither a proposal (future-tense) nor buried inside a whitepaper.
This doc audits every typed document on the site today, cross-references industry patterns, and produces a concrete recommendation. The audit is the deliverable; no docs are moved in this PR. If the recommendation lands, migration is a follow-up issue.
Industry doc patterns (cited)
Section titled “Industry doc patterns (cited)”Eight primary patterns inform the audit. Each entry below summarises the pattern, what rig-docs already does with it, and what it implies for the type question. Full citations in the References section.
Diátaxis (Procida)
Section titled “Diátaxis (Procida)”Four-quadrant framework: tutorials (learning), how-to guides (task), reference (information), explanation (understanding). Diátaxis organises by the purpose of the reader engagement at a given moment, not by the artifact that produced the content. Procida key insight: most doc problems come from mixing purposes in a single document (a tutorial that doubles as reference; reference prose buried in an explanation).
Diátaxis maps imperfectly onto rig-docs because the rig types are artifact-shaped (research = a focused investigation; proposal = a ship plan) rather than reader-intent shaped. That is not wrong — artifact-type taxonomies are legitimate when the authors and readers overlap (engineers writing for engineers and their agents). But the Diátaxis lesson applies: mixing purposes in one folder costs readers more than it saves authors. Which is exactly what whitepapers/ does today (foundation + snapshot).
Architecture Decision Records (Nygard 2011)
Section titled “Architecture Decision Records (Nygard 2011)”Nygard original blog post proposes a short text file per architecture decision, with five sections: Title, Context, Decision, Status, Consequences. Designed for small-scope, consequential choices where the reasoning fades faster than the code. adr-tools (Nat Pryce) implements a numbered-file convention (doc/adr/0001-*.md) with supersedes / superseded-by chains. The community-curated adr.github.io inventory catalogs more than a dozen template variants. ADRs are deliberately smaller than RFCs and design docs — short, focused, one decision per file.
rig-docs already thinks in ADR shape: whitepapers/tool-choices.md advertises itself as an ADR for every pick; proposals/2026-04-18-docs-tooling-decision.md reads exactly like an ADR (problem statement, options, decision, rationale). The schema unused decision type is the natural home. Adopting this pattern adds one folder with a well-understood template and clears out two ambiguous cases at once.
RFC process (IETF RFC 2026, Python PEPs, Rust RFCs, Stripe)
Section titled “RFC process (IETF RFC 2026, Python PEPs, Rust RFCs, Stripe)”The org-internal RFC pattern descends from IETF RFC 2026 (The Internet Standards Process — Revision 3) — a doc proposes a change, circulates for comment, and is accepted, rejected, or superseded. Python PEPs (PEP 1 PEP Purpose and Guidelines) formalised the same pattern for a single language. Rust RFCs (rust-lang/rfcs) run it for a language ecosystem. Stripe, Uber, Cloudflare, and others (documented by Gergely Orosz in The Pragmatic Engineer) use internal RFCs / design docs before any non-trivial project.
RFCs differ from ADRs on three axes: scope (RFCs propose a change; ADRs record one), timing (RFCs circulate for comment before commitment; ADRs are written at or after the decision), and size (RFCs are multi-page proposals; ADRs are single-page records). rig-docs current proposals/ folder is RFC-shaped — future-tense, ship-plan, pre-commitment. Keeping proposals/ as the RFC seat and adding decisions/ as the ADR seat is consistent with this distinction.
Design Docs at Google (Ubl 2020)
Section titled “Design Docs at Google (Ubl 2020)”Malte Ubl Design Docs at Google describes the pre-implementation design document as Google primary engineering artifact: informal, a few pages, focused on the high-level strategy and the tradeoffs considered. Ubl distinction from ADRs: design docs are forward-looking and exploratory; ADRs are retrospective and narrow. A design doc might produce several ADRs as byproducts. The format is intentionally lightweight (a few pages), written before code, and reviewed async.
Google design doc is a cousin of the RFC — same forward-looking shape, slightly less formal, optimised for one team rather than an org-wide audience. For rig-docs, this pattern reinforces proposals/ as the pre-commitment seat (design doc / RFC) and validates keeping it distinct from ADR-style decisions.
C4 model (Brown)
Section titled “C4 model (Brown)”Simon Brown four-level architecture model: Context (system + external actors), Container (runtime units), Component (internal structure), Code (class-level). C4 is a diagramming and layering convention, not a document-type taxonomy. Its relevance to this audit is indirect: the rig foundational whitepapers (memory.md, observability.md, self-healing.md) are largely C4-level-2 explanations (what the containers are, how they relate). That is a strong signal they want the reference type — durable, descriptive, evergreen — which is exactly what they already declare in frontmatter.
User stories (Cohn)
Section titled “User stories (Cohn)”Mike Cohn User Stories Applied (2004) established the canonical form As a [role], I want [capability], so that [outcome] and the INVEST attributes (Independent, Negotiable, Valuable, Estimatable, Small, Testable — the acronym is attributed to Bill Wake). The key Cohn insight: a user story is a placeholder for a conversation, not a spec. User stories travel from product into engineering; they should describe outcomes, not designs.
rig-docs user stories follow the canonical form loosely (2026-04-20-safety-foundation.md: as the rig operator, I want runtime guards…). Most are appropriately outcome-shaped, though several drift toward solution-specification. That drift is the usual failure mode and is not a type problem — it is an author-habit problem. The type itself is well-chosen and should not change.
Blameless postmortems (Google SRE, Etsy / Allspaw)
Section titled “Blameless postmortems (Google SRE, Etsy / Allspaw)”Google SRE book (chapter 15, Postmortem Culture: Learning from Failure) and John Allspaw 2012 Blameless PostMortems and a Just Culture at Etsy established the blameless post-incident writeup as a canonical SRE artifact. A postmortem is neither a decision nor a proposal — it is a retrospective analysis of a specific failure, written to extract reusable learning. Google format typically includes: summary, impact, root causes, trigger, resolution, detection, action items, lessons learned. Etsy framing emphasises that humans had good intentions with the information they had.
rig-docs has no postmortem type today. The rig has not had the kind of customer-facing production incident that would force one — but it has had in-cluster misfires (see research/2026-04-22-egress-policy-pitfall-cloudflare-fronted-apis.md, which is a de facto postmortem filed as research). As the rig moves past pair-mode into autonomous operation, the probability of real incidents rises. Having the type ready before the incident is cheaper than inventing it under pressure.
Runbooks / playbooks (PagerDuty, Splunk, operational literature)
Section titled “Runbooks / playbooks (PagerDuty, Splunk, operational literature)”Runbooks are step-by-step operational procedures for a specific task (restart the proxy). Playbooks are strategic guides for a class of situations (respond to a cost spike). The distinction is scope — runbooks are tactical and often automatable; playbooks are adaptive and human-judged. The schema already has runbook as a type; rig-docs has no folder for it. As the rig ops surface grows (LiteLLM proxy, Envoy egress gateway, rig-conductor), the pressure for a runbook folder is a matter of when, not whether.
Current rig-docs taxonomy
Section titled “Current rig-docs taxonomy”Today state (2026-04-22, before this PR):
| Folder | Files | Frontmatter type | Industry analogue |
|---|---|---|---|
| whitepapers/ | 22 | all reference | Mix of C4 reference (evergreen foundation) and leadership snapshot (dated synthesis) |
| research/ | 18 | all research | Investigation / spike writeup — focused questions, often dated |
| proposals/ | 2 | proposal | RFC / design doc (with one ADR-shaped outlier) |
| user-stories/ | 7 | all user-story | Cohn user stories (with mild drift) |
| reference/ | 2 + facts/ | reference | Operational reference (AGENTS.md mirror, roadmap workflow) |
| brain/ | 9 | n/a (compiled) | Compiled agent context — not author-written |
| implementation/ | 1 (index) | n/a | Dashboard — structured data rendered as page |
Schema allows six types: research | proposal | decision | reference | user-story | runbook. Four are in active folder use; decision and runbook are dormant. reference is used for both whitepapers/ (22 files) and reference/ (2 files) — that mixed usage is the core of the consistency problem.
Per-document verdict
Section titled “Per-document verdict”Verdicts: keep (stay where you are, type is right), keep + retype (right folder, frontmatter type should change), split (genre mismatch — move part into a new folder or annotate with subtype), promote (right content, wrong folder, move to a new or dormant folder).
index.mdx files are not audited.
Whitepapers (22 files) — split by genre
Section titled “Whitepapers (22 files) — split by genre”Two genres share this folder. Foundational whitepapers are evergreen; they describe what the rig is and are updated in place. Leadership snapshots are dated; they describe what the rig roadmap looks like right now and are superseded by newer snapshots.
Foundational (20 files — recommend keep type: reference; consider subtype: foundation)
Section titled “Foundational (20 files — recommend keep type: reference; consider subtype: foundation)”| Doc | Verdict | Reason |
|---|---|---|
| agent-secrets-broker.md | keep | Architecture whitepaper for a specific capability. C4-container-level reference. |
| cost-framework.md | keep | Four-layer enforcement architecture. Evergreen, cross-linked. |
| development-process.md | keep | Operating manual. Describes the three eras, quality gates, rituals. |
| drift-detection.md | keep | Four-channel detection architecture. Evergreen. |
| example-first-story.md | keep | Worked example of the development process. Function is explanation in Diátaxis terms. Stays here. |
| glossary.md | keep | Classic reference artifact. Schema-matching type. |
| implementation-status.md | keep + flag legacy | Prose reference for what is shipped. Frontmatter already flags Partially superseded by /implementation/ dashboard — honest. |
| limitations.md | keep | Explicit enumeration of what the rig cannot do. Evergreen. |
| memory.md | keep | Memory architecture + honest-gap acknowledgement. Evergreen. |
| mvp-scope.md | keep | Scope definition. Evergreen until MVP ships. |
| observability.md | keep | Observability architecture across agent + infra. Evergreen. |
| principles.md | keep | Ten design principles. Evergreen — the document everyone else answers to. |
| provider-portability.md | keep | Vendor-neutrality architecture. Evergreen. |
| quality-and-evaluation.md | keep | Quality measurement architecture. Evergreen. |
| safety.md | keep | Runtime-safety architecture. Evergreen. |
| security.md | keep | Supply-chain + attestation architecture. Evergreen. |
| self-healing.md | keep | Self-healing production architecture. Evergreen. |
| tool-choices.md | keep or promote to decisions/ later | Advertises itself as an ADR for every pick — literally a collection of decisions. Acceptable to keep here if treated as a reference-grade compilation; cleaner to split each tool pick into its own ADR later. Deferred. |
| trust-model.md | keep | Tiered autonomy architecture. Evergreen. |
| 2026-04-22-whitepaper-review.md | promote to research/ | Despite filename and folder, this is a review report (grades A–C per whitepaper). Function matches research type: focused investigation with findings. It declares type: reference, which is wrong for its function. |
Snapshots (2 files — recommend keep type: reference; add subtype: snapshot)
Section titled “Snapshots (2 files — recommend keep type: reference; add subtype: snapshot)”| Doc | Verdict | Reason |
|---|---|---|
| 2026-04-19-brain-and-memory.md | split genre | Dated leadership synthesis. For engineering leadership across the orgs. Not evergreen — a newer snapshot would supersede. |
| 2026-04-20-whats-next.md | split genre | Explicitly raising the floor before raising the ceiling — a point-in-time roadmap synthesis. Explicitly dated, explicitly superseding prior state-of-rig snapshots. |
Both snapshots already live alongside foundational whitepapers and cross-link to them. The split does not require moving them — it requires a clear marker (either folder snapshots/ or a frontmatter subtype: snapshot field) so the sidebar and the RelatedDocs component render them differently from foundation.
Research (18 files) — 17 keep, 1 flag
Section titled “Research (18 files) — 17 keep, 1 flag”Research is the healthiest type. All 18 files are focused investigations of a specific question, dated, with source_refs, often pointing to a user story. The type works.
| Doc | Verdict | Reason |
|---|---|---|
| 2026-04-18-docs-memory-drift-lint.md | keep | Migrated from Plane. Focused research. |
| 2026-04-18-docs-memory-inventory.md | keep | Snapshot of state. Focused research. |
| 2026-04-18-docs-state-audit.md | keep | Ground-truth snapshot. Canonical research shape. |
| 2026-04-18-docs-tools-evaluation.md | keep | Tool comparison, superseded-by a proposal. Canonical research. |
| 2026-04-18-docs-vs-memory-principles.md | keep | Candidate principles. Research. |
| 2026-04-18-llm-wiki-pattern-analysis.md | keep | Karpathy analysis. Research. |
| 2026-04-18-production-docs-patterns.md | keep | Cross-company pattern analysis. Research. |
| 2026-04-20-otel-llm-observability-options.md | keep | 11-stack comparison. Research. |
| 2026-04-21-agent-runtime-install-audit.md | keep | Audit of install behavior. Research. |
| 2026-04-21-brain-pattern-prior-art.md | keep | Prior-art audit. Research. |
| 2026-04-21-egress-policy-options.md | keep | Seven-option evaluation. Research. |
| 2026-04-21-otel-startup-programs-storage-economics.md | keep | Second-pass research. Research. |
| 2026-04-22-cross-repo-access.md | keep | Comparative study. Research. |
| 2026-04-22-egress-policy-pitfall-cloudflare-fronted-apis.md | keep + flag as postmortem candidate | Describes a same-day revert of a shipped policy. Function is postmortem. No postmortem type exists yet; research is the sensible interim home. Flag for migration if a postmortem folder is added. |
| 2026-04-22-envoy-egress-gateway-spike.md | keep | Live spike + final resolution. Research. |
| 2026-04-22-litellm-passthrough-spike.md | keep | Spike writeup. Research. |
| 2026-04-22-litellm-passthrough-spike2-oauth.md | keep | Follow-up spike. Research. |
(A 19th effectively-research doc, 2026-04-22-whitepaper-review.md, currently lives in whitepapers/; see that section.)
Proposals (2 files) — 1 keep, 1 promote
Section titled “Proposals (2 files) — 1 keep, 1 promote”| Doc | Verdict | Reason |
|---|---|---|
| 2026-04-18-docs-tooling-decision.md | promote to decisions/ | Classic ADR shape — context, alternatives considered, decision, rationale, status. Supersedes a research doc. The canonical use case for Nygard ADR template. type: proposal → type: decision. |
| 2026-04-18-stage-a-compiled-agents-md.md | keep | RFC-shaped: one PR to make a specific change, pre-commitment, forward-looking. Correct type. |
User stories (7 files) — 7 keep
Section titled “User stories (7 files) — 7 keep”All seven declare type: user-story, point to a GitHub issue, and link to research that supports them. Most follow the canonical Cohn form.
| Doc | Verdict | Reason |
|---|---|---|
| 2026-04-18-docs-memory-strategy.md | keep | Parent user story tying three research items. Correct type. |
| 2026-04-19-memory-to-docs-promotion.md | keep | Canonical user story. |
| 2026-04-19-two-layer-brain-multi-project.md | keep | Canonical user story. |
| 2026-04-20-agent-observability.md | keep | Canonical user story. Links to research and whitepaper. |
| 2026-04-20-hard-cost-ceiling.md | keep | Canonical user story. |
| 2026-04-20-nightly-quality-gate.md | keep | Canonical user story. |
| 2026-04-20-safety-foundation.md | keep | Canonical user story. Cross-linked to four research docs. |
Reference (2 files) — 2 keep
Section titled “Reference (2 files) — 2 keep”| Doc | Verdict | Reason |
|---|---|---|
| agents.md | keep | Mirror of repo-root AGENTS.md. Reference. |
| roadmap-summary.md | keep | Workflow description. Reference. |
Gap analysis — what types are missing?
Section titled “Gap analysis — what types are missing?”Comparing the current folder-and-schema inventory to the eight patterns surveyed, four gaps stand out.
| Gap | Evidence rig needs it | Industry pattern | Cost to add |
|---|---|---|---|
| ADR / decision | tool-choices.md is an ADR collection; 2026-04-18-docs-tooling-decision.md is ADR-shaped and filed as proposal. | Nygard 2011, adr.github.io, adr-tools. | Low — decision already in schema; one folder, one template. |
| Postmortem | 2026-04-22-egress-policy-pitfall-cloudflare-fronted-apis.md is a postmortem filed as research. LiteLLM passthrough spike #2 is a near-postmortem. | Google SRE Ch. 15; Allspaw 2012. | Low-medium — new type + schema enum + template. |
| Runbook | No operational procedures yet; runbook type in schema but unused. Ops surface growing (LiteLLM proxy, Envoy gateway, rig-conductor). | PagerDuty, Splunk, operational literature. | Low — schema seat exists; needs folder + first two runbooks. |
| Leadership snapshot genre | whitepapers/2026-04-19-* and 2026-04-20-* mix with foundational. | Diátaxis (do not mix purposes); org practice varies. | Medium — either new folder or frontmatter subtype flag. |
A fifth candidate, tutorial / how-to, is deliberately excluded. rig-docs is engineer-facing and agent-facing; the reader is always already inside the system. Diátaxis tutorial quadrant serves external onboarding; there is no evidence the rig needs it yet. development-process.md is the only doc that hints at tutorial shape, and it is adequately served by reference.
Recommendation — C. Add types (decision, postmortem, runbook); sharpen the whitepaper boundary
Section titled “Recommendation — C. Add types (decision, postmortem, runbook); sharpen the whitepaper boundary”Three moves, no consolidation. Each is low-cost and reversible. This picks option C from the three framings (A = keep 4 as-is; B = consolidate to N; C = add types) because the evidence points to under-differentiation, not over-differentiation — the existing four types are doing real work, the schema has two dormant types the content wants, and a new postmortem type is visibly needed as autonomy expands.
1. Promote decisions/ (ADR) to a first-class folder and type
Section titled “1. Promote decisions/ (ADR) to a first-class folder and type”| Element | Action |
|---|---|
| Folder | Add src/content/docs/decisions/. |
| Frontmatter type | type: decision (already in schema). |
| Template | Five-section Nygard: Title, Context, Decision, Status, Consequences. |
| Numbering | Date-prefix consistent with the rest of rig-docs (2026-04-23-descriptive-slug.md). Numbered ADRs (0001-*) are optional; rig-docs date convention reads better in chronological listings. |
| Linkage | supersedes / superseded_by chains already in schema. |
| Seed | Migrate proposals/2026-04-18-docs-tooling-decision.md → decisions/2026-04-18-docs-tooling-decision.md. Splitting whitepapers/tool-choices.md into per-tool ADRs is deferred — too large for the first migration PR. |
Why: Makes the proposal-vs-decision line crisp: proposals are forward-looking RFCs (Ubl 2020 / Rust RFC pattern); decisions are retrospective records (Nygard 2011). The rig will make hundreds of small decisions; writing each as a proposal overweights them and buries them.
2. Split whitepapers/ by genre — foundation vs snapshot
Section titled “2. Split whitepapers/ by genre — foundation vs snapshot”Two viable shapes. Both remove the current mixed-purpose problem.
| Option | Shape | Tradeoff |
|---|---|---|
| 2a. Folder split | whitepapers/ (20 foundational) + snapshots/ (2 dated). | Most explicit; visible in URLs and sidebars. Higher migration cost (2–22 URL changes depending on depth). |
| 2b. Frontmatter subtype | Keep whitepapers/ folder; add subtype: foundation or snapshot to the schema; sort sidebars by subtype. | Lowest migration cost; subtype is a weaker signal than folder but still machine-readable. |
Recommended: 2b first, 2a deferred. The cost of folder renames is real — every external link to a whitepaper URL breaks; brain/ content cross-links into whitepapers; RelatedDocs paths break. Subtype gets 90% of the clarity for 10% of the work. 2a can follow in a later PR if the subtype proves insufficient over two months of usage.
3. Keep runbook/ latent; activate postmortem/ as a new type now
Section titled “3. Keep runbook/ latent; activate postmortem/ as a new type now”- Runbook: schema seat exists; no content exists. Do not create the folder until there is at least one runbook to put in it. The convention is folder-follows-the-first-file, not the other way around.
- Postmortem: the schema does not have this type today. Add postmortem to the enum now and create the folder on the first real incident. Keeping the template ready in reference/templates/postmortem.md is useful; keeping an empty folder is not. Retype the existing egress-policy pitfall research as postmortem once the type lands.
What NOT to change
Section titled “What NOT to change”- Do not merge research and proposal. They are doing different work: research is open-ended investigation (often multiple per question), proposal is pre-commitment ship plan (one per decision). The ADR / RFC / design-doc literature (Nygard 2011; RFC 2026; Ubl 2020; Orosz 2022) is clear these are distinct artifact types. Merging costs more than it saves.
- Do not rename user-stories/. The Cohn terminology is widely understood; the rig already uses the canonical form. Stability costs nothing.
- Do not delete the whitepaper label in prose. Readers and leadership identify with it. It is a useful word for diagram-heavy synthesis aimed at a leadership audience, and that is how whitepapers/index.mdx already describes the folder. Keep the word; sharpen its scope.
Tradeoffs and risk
Section titled “Tradeoffs and risk”Adding three new seats (decision, postmortem, runbook) has a real cost: more places to put a new doc means more author deliberation and more opportunities to miscategorise. The mitigation is convention, not policy — the decision-vs-proposal distinction above is a two-question filter (retrospective or forward-looking? one decision or a change plan?) that most authors can apply on first read. If authors still miscategorise after two months, that is a signal the boundaries were not sharp enough and we revisit — not a signal to consolidate immediately.
The alternative to adding types — option A, keep four as-is and write sharper boundary prose in the existing AGENTS.md — was considered and rejected. The whitepaper-vs-reference mismatch is a structural inconsistency, not a wording problem; prose cannot fix 22 frontmatter disagreements. The proposal-vs-decision conflation is similarly structural.
Migration plan (if the recommendation lands)
Section titled “Migration plan (if the recommendation lands)”The audit is informational. If approved, migration is one follow-up issue per move, not one big-bang PR:
- Schema extension PR. Add subtype: foundation | snapshot (whitepapers), add postmortem to the type enum, document decisions/ folder convention in AGENTS.md.
- Promote proposals/2026-04-18-docs-tooling-decision.md → decisions/. Uses supersedes chain. Redirect the old URL in astro.config.mjs. One small PR.
- Relocate whitepapers/2026-04-22-whitepaper-review.md → research/. Its function is research. One small PR.
- Annotate snapshots with subtype: snapshot. Two one-line frontmatter edits. One PR.
- (Optional, deferred) retype research/2026-04-22-egress-policy-pitfall-cloudflare-fronted-apis.md as postmortem if/when postmortem type lands.
- (Optional, deferred, trigger-based) folder split for whitepapers (2a above). Only if subtype proves insufficient over ~two months of usage.
None of the above changes behavior for agents or for the deploy pipeline. The brain/ content is compiled from facts/*.yaml independently. The main risk is link breakage, handled by redirects.
References
Section titled “References”- Daniele Procida — Diátaxis framework, 2017–present. https://diataxis.fr/. Four-quadrant documentation framework (tutorial / how-to / reference / explanation) organised by the reader purpose. Key point for this audit: mixing purposes in one document or folder is the most common doc failure mode.
- Michael Nygard — Documenting Architecture Decisions, Cognitect blog, 15 Nov 2011. https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions. The original ADR article. Five-section template: Title, Context, Decision, Status, Consequences.
- ADR community — adr.github.io, ongoing. https://adr.github.io/. Curated template inventory and conventions, including MADR (Markdown Architectural Decision Records).
- Nat Pryce — adr-tools, GitHub, 2014–present. https://github.com/npryce/adr-tools. CLI for ADR workflow; introduced the numbered-file convention (0001-*.md) and supersedes/superseded-by chains.
- IETF — RFC 2026: The Internet Standards Process — Revision 3, Bradner, Oct 1996. https://datatracker.ietf.org/doc/html/rfc2026. The canonical RFC process: proposal → comment → standard. Ancestor of every org-internal RFC system.
- Python — PEP 1: PEP Purpose and Guidelines, Warsaw/Hylton/Goodger, 2000. https://peps.python.org/pep-0001/. Applies the RFC pattern inside one language ecosystem. Distinguishes Standards-Track / Informational / Process PEPs.
- Rust — RFCs for changes to Rust, rust-lang/rfcs, 2014–present. https://github.com/rust-lang/rfcs. Org-internal RFC process: fork template, PR for discussion, accept or reject. Every major Rust feature travels through an RFC.
- Malte Ubl — Design Docs at Google, industrialempathy.com, 12 Jul 2020. https://www.industrialempathy.com/posts/design-docs-at-google/. Describes Google pre-implementation design-doc culture. Forward-looking, lightweight, cousin of RFC. Distinguishes design docs (exploratory) from ADRs (retrospective).
- Simon Brown — C4 model, 2006–present. https://c4model.com/. Four-level architecture visualisation (Context, Container, Component, Code). Layering convention; complements rather than replaces doc types.
- Mike Cohn — User Stories Applied: For Agile Software Development, Addison-Wesley, 2004. https://www.mountaingoatsoftware.com/books/user-stories-applied. Established the canonical As a [role], I want [capability], so that [outcome] form. INVEST attributes attributed to Bill Wake.
- Google SRE — Site Reliability Engineering, Beyer et al., O Reilly 2016, Ch. 15 Postmortem Culture: Learning from Failure. https://sre.google/sre-book/postmortem-culture/. The canonical SRE postmortem framework. Blameless, action-item-driven, learning-oriented.
- John Allspaw — Blameless PostMortems and a Just Culture, Etsy Code as Craft, 22 May 2012. https://www.etsy.com/codeascraft/blameless-postmortems. The foundational blameless-postmortem article. Draws from Human Factors and Systems Safety research.
- Gergely Orosz — Engineering Planning with RFCs, Design Documents and ADRs, The Pragmatic Engineer, 2022. https://newsletter.pragmaticengineer.com/p/rfcs-and-design-docs. Cross-company survey of how Stripe, Uber, Airbnb, Cloudflare and others use RFCs / design docs / ADRs. Informs the RFC-vs-ADR distinction.
- PagerDuty — What is a Runbook?, ongoing. https://www.pagerduty.com/resources/automation/learn/what-is-a-runbook. Canonical definition of runbook as a task-scoped operational procedure; distinguishes from playbooks (strategic guides).
Status: research, informational. Next step if accepted: schema extension PR (see Migration plan § 1).