Summary
I use Requests for Discussion (RFDs) to turn ideas into durable written artifacts. An RFD can start rough, but the point is to make the idea visible, discussable, and worth returning to later.
This repo is not only for polished final documents. It is also for:
- early framing,
- technical and process exploration,
- design trade-off capture,
- decisions that I want to preserve,
- references I expect to build on over time.
The determination of this RFD is:
- an RFD is the default format for a meaningful idea that deserves written discussion,
- an RFD may begin rough and become more structured over time,
- good RFDs document both the decision and the reasoning behind it,
- public and private visibility are both valid depending on the subject,
- numbering should stay simple and navigable,
- the collection should read like a working body of thought rather than a pile of disconnected notes.
This approach follows the spirit of RFCs and is strongly influenced by Oxide's RFD process, adapted to a smaller personal and project-oriented setting.
What an RFD is
An RFD is a written request for discussion. It gives an idea a stable place to live so it can be refined, challenged, linked, and reused.
The important property is not polish. The important property is that the idea becomes explicit. Once an idea is written down, I can:
- reason about it more clearly,
- compare it against alternatives,
- invite feedback,
- refer back to it later,
- avoid re-deciding the same thing from scratch.
In that sense, RFDs sit somewhere between notes, proposals, design docs, and permanent references. Some are tactical. Some are architectural. Some are workflow documents. Some are mainly educational. What they share is that they are worth preserving as first-class documents.
When to use an RFD
I should reach for an RFD when a topic would benefit from persistence and discussion rather than disappearing into chat, a scratch file, or memory.
Common examples include:
- a software or hardware design direction,
- a workflow or process change,
- a tool or environment setup that should be repeatable,
- a system architecture choice,
- a prototype plan,
- a technical reference that I expect to extend,
- a decision with meaningful trade-offs,
- a topic where future-me will care not just about the answer, but why I chose it.
An RFD does not need to represent a finalized commitment. In many cases the right time to write one is before the idea is settled. Writing is part of the thinking.
What good RFDs include
The best RFDs do more than announce a conclusion. They make the surrounding judgment visible.
A strong RFD usually includes some combination of:
- the problem being addressed,
- the scope and constraints,
- the relevant context,
- the viable options,
- the trade-offs of those options,
- the preferred direction,
- the determination,
- practical implications,
- references or evidence.
For technical topics, I especially want the document to help me later answer questions like:
- What was the actual problem?
- What alternatives were considered?
- Why did one option win?
- What assumptions did this depend on?
- What should change if those assumptions stop being true?
Not every RFD needs the same rigor. A small workflow note does not need the same treatment as a foundational architecture decision. The right level of detail depends on the cost of being wrong, the expected lifespan of the idea, and how likely I am to need the reasoning later.
State model
Each RFD has a state in frontmatter.
The state communicates how settled the document is and how I should interpret it.
prediscussion
The topic exists and I know I want to work on it, but the document is still being roughed in. This is an active drafting state.
ideation
The topic is worth capturing, but it is still closer to a scoped idea than a finished proposal. This is useful for preserving intent even before I have developed the full argument.
discussion
The RFD is being actively worked through with others or against a concrete implementation path. The document is mature enough to invite pointed review.
published
The RFD is part of the durable body of documents in this repo. Published does not mean immutable. It means the document is coherent enough to stand as a reference.
committed
The idea described by the RFD has effectively become the adopted direction and has been materially carried through. This is stronger than published. It indicates that the RFD describes reality or a decision I am treating as established.
abandoned
The idea is intentionally not the path forward. I still want the document preserved so the dead end stays legible and the reasoning is not lost.
Visibility and access
Not every RFD should be public. Some topics are fine to publish broadly, while others are better kept private and shared only with specific GitHub accounts.
That means this repo intentionally supports both:
- public RFDs that anyone can read, and
- private RFDs that require sign-in and explicit allowlisting.
Visibility is a property of the document, not of the entire collection. A document can be worth preserving even if it is not worth publishing to everyone.
As a result, the public catalog should be coherent on its own. If a document is private, that should not make the public-facing set feel confusing or broken.
Numbering and continuity
RFD numbers are part of the address and part of the reading experience. I want the collection to stay easy to browse.
That means:
- numeric slugs are the canonical identity of an RFD in this repo,
- numbering should remain simple and sequential where practical,
- renumbering is acceptable when it materially improves the clarity of the public corpus,
- cross-links should use explicit local RFD links such as 0002.
The goal is not archival purity at all costs. The goal is a collection that remains understandable.
How I expect to write these
I prefer a style that is direct, structured, and useful. For many RFDs that means sections such as:
- Summary
- Problem
- Constraints and goals
- Options considered
- Applied configuration or proposed approach
- Trade-offs
- Determination
- Future work or open questions
That structure is not mandatory. It is simply a good default because it balances readability with permanence.
For authoring mechanics in this repo, including MDX-specific examples, see 0002.
Determination
RFDs in this repo are the primary durable format for discussing and preserving important ideas. They are intended to be practical, revisable, and worth rereading.
The core determination is:
- write ideas down early,
- keep the reasoning with the decision,
- allow documents to mature over time,
- use visibility intentionally,
- keep the collection navigable,
- optimize for future clarity over ceremony.