Decision documents, product intent, proposals and records in one register

Problem

On 2026-10-07 the owner asked every session to read an article on decision documents (PRD, ADR and RFC) and compare it with how we work. Six areas of the platform sent what they miss. This RFC collects that, says where we stand, and proposes what to adopt in the RFCs product.

What the article proposes

The article separates three documents by the job each does:

• PRD (product requirements document): the product intent, what and why, written before the design. It is frozen when the team commits to it.
• RFC: a proposal for a decision not yet made. It names who decides and by when, carries real alternatives, ends Accepted, Rejected or Superseded, and keeps its discussion as an archive.
• ADR (architecture decision record): one decision, immutable. Status, context, decision, consequences. It is never edited; a later decision supersedes it with a new record. ADRs live with the code (docs/adr/NNNN-...).

The pipeline is PRD, then RFC, then ADR, with the ceremony sized to the change. The article names three anti-patterns: RFCs written after the thing is built (review as theatre), ADRs rewritten instead of superseded, and PRDs that specify the solution. It also argues that the three together give an AI agent what it needs to act: the intent, the chosen approach and the constraints.

Where we are today

We have one strong layer and gaps around it.

The RFC layer works. 102 RFC files exist in the repository export on 2026-10-07; since that day each lives in the RFCs product with versions, comments, reviews, access levels (RFC 0065) and diagrams, and agents keep them current through the API. 98 of the 102 carry an "Alternatives considered" section. RFC 0080's second slice, live since 2026-10-07, lets an agent append a status-log line, set a delivery stage and claim a number without a full save.

Owner decisions have no record. They are made in a chat and relayed by an agent, sometimes through two or three sessions. Pricing and site work (RFC 0078.1) received the same relay twice; other relays reached the wrong session or contradicted an earlier one. What was decided then lives wherever the relaying agent put it: a status-log line, a memory file, a line on the team board, a decided list in the pricing model. Examples from 2026-10-06 and 2026-10-07: the marketplace's 20 % share, business customers only and the VAT gate "pending the accountant" (RFC 0073, in prose); /v1/rfcs as the canonical path; the plugin's name; no AI attribution on commits and pull requests; the release decisions for the company front page, prices and a hidden Lab; partners who may be individuals. An agent that needs one of these has to find it, and cannot tell whether it is still current.

Superseding is invisible. The Team plan's minimum went from three seats to two to one (RFC 0052), and "the company page is gated" became "the front page for everyone" within a day. Each change is one more status-log line; the current truth takes reading the whole log.

Decisions taken while building have no home. The sign-in work for MCP clients (RFC 0050) took fourteen security decisions the plan had not pinned: strict URL rules, when a client record is deleted, budgets, an authorization check at the edge in place of a redirect loop. They live in one pull request's description and one status-log line.

Decision text drifts. An RFC is a living document, so "what was decided" moves with it. RFC 0073's decision text moved between sections across versions, and an import from the repository once replaced RFC 0055's text saved through the API (RFC 0080's source flag now prevents that one).

Status mixes decision and delivery. An RFC is open, decided or superseded. 86 of the 102 files say open, including RFCs whose work is live. RFC 0080 added a delivery stage (proposed, building, in review, partly live, live, abandoned) beside the status; the status itself still has no "in review", "accepted" or "rejected".

Review has no decider and no deadline. RequestReview records a pending review and a space requires one approval by default. Nobody is named as the one who decides, there is no review-by date, and the rule in practice is "ask the owner". Security review blockers (the data plane's #17, core's #492 and #529) live in agent reports and chat until RFC 0080's issues slice lands.

Decision records exist in three places, with no index. The SDK repository keeps 15 ADRs (docs/adr/0001 to 0015), the data plane 2, and the compliance programme a register of 18 decisions (D-001 to D-018). Core has none: its standing decisions sit in RFC text and in the agents' instructions (the edge is the only authenticator, services never verify tokens, migrations are named by time). The SDK's own README says an old record "stays with its status updated", and its record 0004 shows what that becomes: the status line carries an amendment and a shipping note, delivery mixed into the decision again.

There is no PRD layer. Product intent exists, scattered. The product direction (RFCs 0045 to 0047 and their working summary) is a PRD for the whole platform in all but name. Below it, the marketplace was decided in conversation and then written as RFC 0073 with the owner's answers in prose; pricing ("1 to 10 per user", euro and dollar prices, Team from one seat) is spread over a handoff file, the board, the pricing model and RFC 0052's log; the capture direction ("every edge connected", AI on paid plans only, never on the free plan) and the local console exist in plan files and memory.

Non-goals matter here beyond product: "no decrypted TLS" and "no health data" are compliance boundaries, and today they are written down only where someone remembered to.

Control changes are recorded in pull request text. Three pull requests on 2026-10-06 and 2026-10-07 (#500, #504 and #519) each changed a control the compliance programme tracks for its SOC 2 alignment. The change was noted in each description, as our rules ask. Nothing links the control in the registry to the decision that changed it.

RFCs are written while building. Our rule is to write the RFC and keep coding without waiting for approval when that is safe. The article calls an RFC written after the build theatre. Ours are not after the fact, and they are not debates either: the design is written as it is built, and the owner reviews it once it exists. That works for our pace. What does not work is when the RFC then reads as if alternatives were weighed and a decision taken before the code, with no record of who decided and when.

What works and should be copied. Our strongest pattern is a decision a machine checks. Pricing has a test that fails CI when the published catalogue drifts from the pricing model; the no-attribution rule has attribution:check in the CI gate. Neither decision is written anywhere as a decision; both are enforced.

The question for the owner: separate ADR and PRD services, or document types?

The owner asked (2026-10-07, relayed by seo-worker) whether ADRs and PRDs should get services of their own that work together with the RFCs.

Recommendation: no new services. ADRs and PRDs become document types in the RFCs product (the labs service), next to rfc and study. Each type then has, from the first day, what RFCs already have:

• spaces, the five access levels and the per-reader classified cut;
• versions, comments, reviews and approval, diagrams, search and the timeline;
• import and export, the public read path, the API, MCP and iohr rfc.

Separate services would have to build each of these again, keep two or three permission models in step, and join across services to show one document's history.

The types work together through typed links:

• a PRD is realised by RFCs;
• an RFC is decided by ADRs (decision records);
• an ADR supersedes an older ADR.

The console shows them as one tree, PRD → RFCs → ADRs. iohr rfc gains adr and prd commands. In the console and the command line the decision type is called adr, the owner's word; this RFC's text calls the same record decision. It holds architecture choices and owner decisions alike.

The types differ in how their text may change:

• a PRD is living while drafted and frozen when the owner accepts it; a later change is a new version, reviewed again;
• an RFC is living while under review, then resolved;
• an ADR cannot be edited once accepted; a change is a new ADR that supersedes it.

Trade-off: the product's name, "RFCs", may want a broader one later ("Decisions", "Records"). That is naming, not code. The SDK's and the data plane's docs/adr files are imported into the same register (slice 6).

Proposal

The article's three documents map onto the RFCs product without a new product: two new document kinds in the same spaces, so access levels, the classified cut, versions, comments, reviews, diagrams and RFC 0080's facts apply to them as they do to RFCs today.

A diagram is drawn here in the RFCs product; this page does not show diagrams yet.

1. Four kinds of document

kind gains prd and decision everywhere it is read: CreateDocument, ListDocuments, the public read path (/v1/rfcs/public/spaces/{space}/{kind}/{number}), the export (docs/prd/NNNN-slug.md, docs/decisions/NNNN-slug.md), the import, mentions ("PRD 0003", "Decision 0012" are recognised like "RFC 0018") and the console's filters.

Numbering. One sequence per kind per account, across its spaces. Our own accounts already number RFCs across spaces when a number is claimed (RFC 0080, slice 2); without a claim, a new RFC in the llm or evm space still takes the next number of that space and collides with a platform number. The rule becomes the same for every account and every document type: the next free number of that kind in the account. Existing numbers are kept; nothing is renumbered.

2. Decision state and delivery stage, kept apart

A document has two independent fields.

Decision state (the status field, per kind):

in_review requires a named decider and a review-by date (section 5). Today's open reads as draft, or as in_review when a review is pending; decided reads as accepted. The old names stay accepted on the API for one release, as aliases.

Delivery stage is RFC 0080's stage: proposed, building, in_review, partly_live, live, abandoned, with partly_live and live computed from recorded rolls (RFC 0080, slice 3). Its in_review means code in review; the console labels it "code in review" so the two are not confused. A PRD and a decision have no stage of their own: a PRD shows the stages of its RFCs, a decision shows whether it is live (section 6).

The two combine without rules between them. An RFC can be accepted and building, or in_review and already partly_live (built while written, section 9).

3. The decision record

A decision document is one page with three required sections, ## Context, ## Decision, ## Consequences, and these fields beside the text:

Write-once. While proposed, the text can change. On accepted the text and fields freeze: a save is refused with "an accepted decision is changed by a new decision that supersedes it". What can still change are facts about the record, each with who and when: the superseded_by link, the decider's confirmation of a relayed record, and the enforcement result. This is the SDK's practice made mechanical: the record's text is never edited, and its status changes beside it.

Superseding. A new record names the one it replaces; the old one becomes superseded, is shown struck through with a link forward, and stays readable at its own level. "What is the current rule" is one lookup: follow superseded_by to the end.

How an RFC and a decision move, with the relay path:

A diagram is drawn here in the RFCs product; this page does not show diagrams yet.

One model with RFC 0080's decisions. RFC 0080 section 3 designs a decision as a question asked on a document (AskDecision, options, an answerer, a due date) and its answer (AnswerDecision, relayed or not, never edited, replaced by a new one). This RFC builds that slice as the decision kind instead of a second store: AskDecision creates a proposed decision record linked from the asking document, with the question as its context and the options in its text; AnswerDecision accepts it with the chosen option, the decider and the date. A decision taken without a question (the owner decides in a chat) is filed directly as accepted with CreateDecision. RFC 0080's decisions table keeps the question and answer; the record is the document that carries them. Nothing is built twice.

4. Links: from intent to a running check

Typed links between documents are RFC 0080's "cross-RFC links" wish; this RFC names the ones decision documents need, each written as a fact and shown on both ends.

• PRD → RFC: realises. An RFC names the PRD it serves; a PRD lists its RFCs with their decision state and delivery stage. RFC families with a common intent (RFC 0040's parts, the phone app's parts) get one PRD as their parent.
• RFC → decision: decided_by. An RFC lists the decisions it rests on and those it raised. When an RFC is accepted, its ## Decision section is copied into a new decision record (decider and date from the acceptance), linked back. From then on, a change to that decision is a new record that supersedes it, and the RFC's text can move on without the decision moving with it.
• Decision → pull requests and rolls: the implementations fact of RFC 0080 (slice 1) applies to a decision as to an RFC. A pull request that implements a decision says so in its description with a line Implements: Decision 0012, matched like the RFC line.
• Decision → check: enforced_by. A decision is live when its enforcing check passed on the commit a recorded roll runs. Until the code host's check results reach the product (RFC 0080, slice 6, which waits on the owner granting the App read access to checks), the roll gate records the result: it already runs the tests of what it ships, and it records a pass for each named check it ran. A decision without a check shows "not enforced by a check". Many decisions cannot be tested, and saying so is enough.

5. Review and approval per kind

The space's one setting (approvals_required) becomes a policy per kind:

Two rules hold for every kind:

• Outward-facing changes need the decider's own approval. A record whose scope is outward-facing (section 3) cannot be acted on while it is only relayed: the console and the API show it as waiting for confirmation, and agents are instructed to wait. The pricing work once had to confirm a relayed decision with the owner directly before making a page public; the rule makes that the default.
• Silence is not consent. A passed review-by date marks the review overdue on the home and on the decider's phone (RFC 0080, slice 9). It never accepts anything.

6. Templates and required sections

Each kind has a template, and the document checks (RFC 0080's CheckDocument, slice 4) report a missing required section as a finding, by rule id and line. A finding never blocks a draft from being saved. It is shown to the decider when review is requested.

A decision over 6000 characters gets a finding ("a decision record is one page"). A prd with an implementation section gets one ("a PRD says what and why; the design belongs in an RFC").

7. Which document do I need

The guide goes into the contribution guide and the agents' instructions, which also gain one rule: an agent that relays an owner decision files a decision record at that moment and acts on the record, and an agent that receives a relay checks the record before acting on the chat.

8. Access levels on every kind

Every document of every kind carries its access level from creation (RFC 0065), and the redaction, strict and leak checks run on each kind's public cut. For decisions:

• A record's default level is the level of the document it governs, or team when it governs none. words carries its own level, never below the record's: the owner's exact words in a chat are often fit for the team and not for the public page.
• Superseding never changes a level. The old record keeps its level and stays readable at it; its "superseded by" link names the successor only to readers who can read the successor, and says "superseded on DATE" to the others. Raising a record's level is an explicit SetAccess by a manager with a reason, audited, never a side effect.
• A record imported from a repository starts at the repository's visibility (public for the SDK and the data plane) and stays at team while its public cut has findings.

9. Our pace, written down honestly

We keep coding without waiting for approval when that is safe. The documents say so instead of hiding it:

• An RFC whose first implementing pull request merged before it entered review is labelled "written while building", computed from RFC 0080's implementation facts and the document's history. Nobody types it.
• "Alternatives considered" lists what was actually weighed. When nothing was weighed before building, the section says that and lists what the review should still consider.
• The decision is recorded explicitly when it is taken, with the decider and the date: an RFC accepted after its code went live says "accepted on DATE by NAME, after it went live on DATE".

That keeps the article's point (a review that cannot change the outcome is theatre) and our pace (the design is written as it is built, and a decider can still reject it).

10. One register: the records other repositories keep

• SDK and data plane. Their docs/adr records are imported as decision documents with the repository field, their own number kept as an alias ("SDK 0004" resolves to its account number). The files stay in their repositories, beside the code, which is where the article and their readers expect them; the import keeps the product in step and refuses a changed text on an accepted record, reporting it instead. Status lines that carry delivery notes (the SDK's 0004) are imported as a status plus a status-log line.

• Compliance. The programme's register (D-001 to D-018) stays where it is: it is the programme's evidence and its own policies point at it. Importing it, at internal, is an open question (below).

• Core. Core gets its first decision records, written from the rules it already lives by, each with its decider, the date it was decided (from the history where it is known, "before DATE" where not) and, where one exists, its enforcing check:

  • the edge is the only authenticator, and services never verify tokens; they read the verified claims the edge forwards;
  • services never address each other directly; calls go through the edge's load balancer;
  • protocol handlers translate and forward; business logic lives in the engine;
  • migrations are named by their UTC creation time, never by the next free number;
  • every new environment variable is a flag with an environment name, registered on every configuration surface;
  • release builds keep symbols and frame pointers, and development builds keep line tables only;
  • stub values are labelled as stubs on every surface;
  • commits and pull requests carry only the owner as author (2026-10-07, enforced by attribution:check);
  • the published price catalogue is the pricing model (enforced by the_catalogue_is_the_pricing_model).

11. Control changes leave a decision

A change that implements, weakens or removes a control gets a decision record, at internal or team, linked from the control's entry in the compliance registry: each control gains a decisions list of record numbers, and the registry's check validates that each number exists in the export of the register. The pull request keeps its line saying which control it changes and adds Implements: Decision NNNN. Back-filling the three changes of 2026-10-06 and 2026-10-07 is the first use.

Coming from the Atlas PRD: repositories, files and services, one space per system

The owner's Atlas PRD (in review on 2026-10-07) adds two things this register must hold. First, documents point at repositories, files and services as first-class things, not as text: a PRD names the systems it concerns, an RFC the repositories and services it changes, an ADR the files or services it constrains. These are typed links beside the document-to-document links above, so "which decisions govern this service" and "which RFCs touched this repository" are queries. Second, each evaluated system gets one space, so a customer's system and its PRDs, RFCs and ADRs live together under the space's access rules. The kinds, numbering and links in this RFC are built so both fit without changing their data; the link targets themselves arrive with Atlas.

Controls

• Access control. The new kinds use RFC 0065's read function and levels unchanged. A decision's words field is read through the same function with its own level.
• Change management. Control changes gain a durable trail from the registry to a decision and from the decision to its pull requests and rolls (section 11). This strengthens the change-management trail the programme tracks; no control is weakened.
• Audit. One audit line per write: who, the account, the document, the kind, the outcome. Never a title, words or text.
• Customer data. Decision text and words are customer data for customer accounts: never in a log line, metric label, event or URL.

Slices

Each slice is shippable alone, has its own pull request, and is recorded on this RFC through the API when it lands. Owner: lab-saas-work unless someone takes a slice on the team board. Where a slice overlaps RFC 0080, it is that slice, built once.

1. The two kinds and account-wide numbering. prd and decision in the labs service and every read and write path, export paths, mentions, the console filter; numbers per kind per account for every account. The rfcs:doc task gains --kind prd|decision. Overlaps nothing in RFC 0080; completes its slice 2 number rule. Acceptance: a decision created in the llm space takes the account's next decision number; an RFC created there without a claim no longer collides with a platform number; "Decision 0001" in an RFC's text links to the record.
2. The decision record = RFC 0080 slice 5. The fields of section 3, write-once on acceptance, CreateDecision, AskDecision and AnswerDecision on the same record, relayed and confirmed, superseding with the struck-through view. Acceptance: RFC 0080 slice 5's, plus: a save on an accepted record is refused; a superseded public record whose successor is team shows "superseded on DATE" to an anonymous reader and no link; an outward-facing relayed record shows "waiting for the decider".
3. Decision state apart from the stage. The new statuses per kind, the decider and review-by date on in_review, the aliases for open and decided, overdue reviews on the home. Uses RFC 0080 slice 2's stage as it is. Acceptance: in_review without a decider is refused; a passed date marks the review overdue and changes nothing else.
4. Templates and findings = part of RFC 0080 slice 4. The templates of section 6 and the required-section rules in CheckDocument. Acceptance: a draft PRD without non-goals saves and returns one finding; a decision over a page returns one finding.
5. The first records. Core's decision records of section 10, the owner decisions of 2026-10-06 and 2026-10-07 listed under "Where we are today" filed with their words and relays, and the three control changes back-filled (section 11, with the compliance registry's decisions field in the compliance repository). Written through the API; no code. Acceptance: each record has a decider and a date; each control change in the registry names a record that exists.
6. Import from repositories. The SDK's and the data plane's records with the repository field and aliases; the import refuses a changed accepted text. Acceptance: all 17 imported; editing an accepted file's decision text makes the next import report it and change nothing.
7. Links and live. realises and decided_by links (part of RFC 0080 slice 10's typed links), the RFC's Decision section frozen into a record on acceptance, Implements: Decision NNNN (RFC 0080 slice 1's parser), enforced_by with results recorded by the roll gate (RFC 0080 slice 3). Acceptance: accepting an RFC creates one linked record; a decision whose named test passed on a rolled commit shows live; a failing one shows "check failing" with the commit.
8. PRDs for what exists. Written through the API: the platform's product direction as PRD 0001 (RFCs 0045 to 0047 realise it), pricing, the marketplace and capture, each at the level its content allows. Acceptance: each PRD lists its RFCs with their state and stage.
9. The guide and the instructions. Section 7 in the contribution guide, the agents' instructions and the board's header; the "written while building" label (section 9).

Order: 1, 2, 5, 3, 4, 6, 7, 8, 9. Slice 5 comes early because filing the owner's decisions is the gap that costs most today, and it needs only slices 1 and 2.

Alternatives considered

• Decision records as repository files only, as the SDK does. It keeps them beside the code, which the article recommends, and needs nothing built. It also keeps three registers with no index, no access levels (a decision with private words cannot sit in a public repository), no link to rolls or checks, and no way for the owner to decide from the phone. The import in slice 6 keeps the files for the repositories that have them.
• A wiki. Easy to write in, and the place decisions go to be lost: no numbers that hold, no write-once rule, no access levels the platform enforces, and a second product to run.
• Keep the status log as the decision record, in prose with stricter wording. It is what we do now. It cannot answer "what is the current rule" without reading every line, it moves with the document's text, and it gives an agent nothing to check before acting on a relay. RFC 0080 already makes the status log a rendered view of typed facts; a decision is one more fact type.
• Decisions as RFC 0080 facts only, without a document kind. Smaller: a row on an RFC. A row has no number to cite in a pull request, no page, no comments, and nothing to hang a decision on when no RFC exists (most owner decisions). The document kind gives all of that and keeps RFC 0080's question and answer as its flow.
• A prd section inside each RFC instead of a kind. It repeats the intent in every RFC of a family, where it then drifts; the phone app's and the marketplace's intents are examples of exactly that.

Trade-offs

• Two more kinds mean more to choose from. The guide in section 7 and the templates keep the choice short, and "none" remains the most common answer.
• Write-once decisions mean more records: a typo in an accepted record is a superseding record. We accept that; the SDK has lived with it for 15 records.
• Account-wide numbers change what a new document in a non-platform space is numbered. Existing numbers stay; only new documents are affected.

Open questions

• Should the compliance programme's register move into the product at internal, or stay in its repository with a link from each record? The register is audit evidence; its location is the programme owner's call.
• Should a decision's decider ever be a role (the security officer) instead of a person? Today every decider is the owner; a second person changes that.
• Does a PRD freeze on acceptance like a decision, or stay living with re-review? This RFC proposes re-review of each new version; the article freezes it.

Decision

Decided by the owner on 2026-10-07 (relayed by mac-mobile): the RFCs product becomes the home of three document kinds, PRDs, ADRs and RFCs, and is renamed later to fit. The API and the data model for all three are built now (a kind field, templates, statuses and review rules per kind), so the rename changes labels, not data. ADRs and PRDs are document kinds in this product, not services of their own. Building starts with slices 1, 3 and 4 (kinds and numbering, decision state, templates), with the review notifications of RFC 0080 slice 9 alongside.

Publication

The RFCs reference gains the kinds and fields as their slices land. The Lab lists PRDs and decisions beside RFCs. The contribution guide gains section 7.

Status log

• 2026-10-07: opened at the owner's request (team board, decision documents), written by lab-saas-work from the article and the bullets of six areas: sign-in and paging, billing and the SDK, capture and the marketplace, pricing and the company site, the RFCs product, and the site and classified RFCs. Nothing is built. Two diagrams made through the API and embedded. Written while RFC 0080 slice 2 was live; slice 5 of RFC 0080 is proposed here as the decision kind's first slice.
• 2026-10-07: The owner asked whether ADRs and PRDs should be services of their own; a section now puts that question first with the recommendation: document types in the RFCs product, linked as one tree (lab-saas-work, relayed by seo-worker).
• 2026-10-07: Decided by the owner (relayed by mac-mobile): PRDs, ADRs and RFCs as the product's three kinds, built now so a later rename changes labels, not data; the Atlas PRD's links to repositories, files and services and one space per evaluated system folded in. Building starts with slices 1, 3 and 4.
• 2026-10-07: Stage building: The owner decided on 2026-10-07; slices 1, 3 and 4 start
• 2026-10-07: This RFC implements PRD 0001 (InOrbit Atlas, approved 2026-10-07) for its documents line (A1): the three kinds, links to repositories, files and services, one space per evaluated system, and review notifications.
• 2026-10-07: Slice 1 merged (core #581, 8f91d3d2): prd and adr kinds beside rfc and study on every path (create, lists, public read, export and import by folder docs/prds and docs/adrs, mentions, rfcs:doc --kind); numbers per kind across the account's spaces, existing numbers kept. Not rolled: needs db:migrate, then labs and protocol.
• 2026-10-08: The product is named Decisions (HR Odluke), under Atlas (owner; PRD 0001 question 8): a label, the API (/v1/rfcs), iohr rfc and the data keep their names. The console moves to /decisions/ with every /rfcs/ and /lab/ address redirected, one section for PRDs, ADRs and RFCs (overview, one list across kinds, typed links both ways, a decision map, how it works), the app says Decisions, and docs/decisions explains the model; inorbithr/core#610, open, not rolled.