RFD-0001 — RFD process

Question

How does this monorepo capture design rationale, and how does that artifact relate to the rest of the documentation surface?

Context

The orca-mvp tree had accreted ~8 substrates that each claimed authority over some flavor of design content: a decision registry (141 D-NNN files), cluster RFC folders that mixed spec / decision / work-tracking, a master design doc duplicated between codebase and other docs, scattered AGENTS.md files carrying global rules, plus 12 mega-plan docs in /docs/. Status lived in 4–6 mirror sites that drifted independently. The book has been actively wrong because contradicting sources fed into it.

The fix is to define one canonical home per artifact type and stop maintaining the duplicates. RFDs replace decisions/ + RFCs/ + master-doc decision logs as the single home for design rationale. They do not subsume specs (those live in rustdoc + book) or work tracking (GitHub).

Decision

RFDs as defined in rfd/README.md are the only place this monorepo records committed design rationale. One question per RFD, one position per RFD, immutable once committed except for typo and clarity fixes. When a position changes, a new RFD supersedes the old one.

RFDs do not track work. A committed RFD that requires implementation produces zero, one, or many GitHub Issues that cite the RFD; those issues track the work, not the RFD itself.

RFDs cover the whole monorepo. Single namespace at /rfd/ at the repo root. Argon, kernel, tide, platform, tools, userspace — all share the namespace. Cross-cutting decisions are common enough that per-system RFD trees would just create boundary problems.

Discussion happens on the PR that lands the RFD. PRs are the durable forum. Discussion outside the PR is allowed but the PR comment thread is the canonical record.

Rationale

Why “Discussion” and not “Comment”. The Oxide framing — Request for Discussion — names the value. The decision matters; the rationale matters more. RFDs that only record “we decided X” without “and here’s why we ruled out Y” are useless when context shifts. Treating each RFD as a discussion document forces the author to surface tradeoffs.

Why one position per RFD, not one topic. Topics drift. Positions don’t. “How do packages work” is a topic; “Bivalent lockfiles use content-hash + constructs-hash” is a position. The latter is what an agent or contributor needs to look up later.

Why work tracking is separate. Cluster RFCs in the previous system tried to be spec-and-decision-and-task-list-and-status-tracker simultaneously. Each role wants different update cadence: specs evolve continuously, decisions land once and freeze, task lists shift weekly, status changes daily. Bundling them produced mirror-site drift. RFDs commit to the freeze-once role; everything else moves to its native home.

Why a single namespace, not per-system. Many positions are cross-cutting (multitenancy model, error code conventions, version-bump grammar, how foreign-format support is exposed). Per-system trees force every cross-cutting decision into a “where does it go” debate. Single namespace means the question never comes up.

Why supersession instead of editing. A reader looking at code from a year ago needs to know what the rationale was at THAT time, not what we think now. Edit-in-place destroys that history. Supersession preserves it: the old RFD stays, marked superseded, and the reader can follow the chain.

Why RFDs do not deprecate the AGENTS.md tree. AGENTS.md files are intent nodes for the system that help organize agents working on each part of it. That’s an orthogonal axis from RFDs (which capture why we chose X); the two surfaces don’t overlap.

Consequences

• The book’s appendix-e-decision-archive.md is deleted (decisions live in /rfd/, not in the book).
• Master design doc §9 Decision log deletes (decisions D-128 through D-131 migrate to RFDs).
• New decisions land as RFDs. No more D-NNN registry.
• Code, docs, and issues cite RFDs by number: RFD-0014 or rfd/0014-foo.md.