RFDs — Requests for Discussion

Design rationale for the orca-mvp monorepo. RFDs cover any system in this tree: argon (language + Oxide toolchain), kernel, tide, platform, tools, userspace.

What an RFD is

An RFD captures a single design position and the rationale behind it. One question per RFD. Once committed, the rationale is the durable answer; if a future RFD changes the answer, the old RFD is marked superseded and the new one cites it.

RFDs are not work-tracking artifacts. Implementation work that flows from a committed RFD lives in GitHub Issues that cite the RFD. Closing all the issues does not close the RFD; the RFD stays committed as the rationale of record.

What an RFD is not

• Not a spec. Specs live in rustdoc (code surfaces) and the Argon book (language surface). RFDs reference those for the “what got built” but don’t redefine them.
• Not a task list. Use GitHub Issues + Project boards for active work.
• Not a status board. Cluster status, release readiness, in-flight work — all live in GitHub Projects.

Layout

rfd/
├── README.md                       this file
├── 0001-rfd-process.md             how RFDs work
├── NNNN-<slug>.md                  one position per file
└── archive/                        superseded or abandoned RFDs (optional; usually we just leave them in place with state field set)

Numbering

• Four-digit zero-padded, monotonic.
• Numbers are assigned at draft time in the PR that introduces the RFD.
• Once a number is assigned and the PR opens, the number is burned even if the RFD is abandoned (the file lands with state: abandoned).
• Gaps are normal; never renumber.

Lifecycle

Each RFD carries a state field with one of:

• discussion — drafted, open for comment. The PR is the discussion forum.
• committed — ratified; the rationale is in force. Body frozen except clarifications.
• abandoned — opened but the position was dropped. Body frozen.
• superseded — replaced by a later RFD. superseded_by: field carries the replacement’s number. Body frozen.

State transitions:

• discussion → committed on PR merge after ratification.
• discussion → abandoned on PR close-without-merge or explicit abandonment.
• committed → superseded happens only when a new RFD lands that explicitly supersedes this one.

Metadata block

Each RFD opens with a small HTML metadata block right after the H1. argon-theme.css styles it as a colored status pill plus a muted meta strip; in the canonical /rfd/ markdown view it renders as plain text. The shape:

<div class="rfd-meta">
  <span class="rfd-status rfd-status-committed">Committed</span>
  <span class="rfd-meta-line">Opened 2026-05-03 · Committed 2026-05-03</span>
</div>

Status-pill classes correspond to lifecycle states:

• rfd-status-discussion — open, drafting (yellow)
• rfd-status-committed — settled, in force (green)
• rfd-status-superseded — replaced by a later RFD (slate, line-through)
• rfd-status-abandoned — dropped without resolution (orange)

The meta line carries dates inline (Opened YYYY-MM-DD · Committed YYYY-MM-DD). For a superseded RFD, append · Superseded by <a href="NNNN-slug.html">RFD-NNNN</a>.

Body shape

Lightweight; not bureaucratic. Use the sections that fit the question; skip ones that don’t apply.

1. Question — one paragraph stating what’s being decided.
2. Context — what’s hard about this, what changed, what depends on it.
3. Options — alternatives considered (skip if there’s only one obvious answer).
4. Decision — the answer (only when state is committed).
5. Rationale — why; the load-bearing reasoning future readers need to make consistent calls.
6. Consequences — what changes downstream (which crates, docs, tests, conventions).

How to land an RFD

1. Pick the next free number. Create rfd/NNNN-<slug>.md with state: discussion.
2. Open a PR titled RFD-NNNN: <title>.
3. Discuss on the PR. Body iterates as the discussion converges.
4. Once ratified: flip state to committed, set committed: date, merge.
5. Cite the RFD from any code, doc, or issue that depends on the rationale.

How to supersede an RFD

1. Open a new RFD (next free number) with the new position.
2. New RFD cites the prior in its body and explains what changed.
3. On merge: flip prior RFD’s state to superseded, set superseded_by field. Do not modify prior body content beyond that.

Index