Docs
Decisions
PRDs, ADRs and RFCs in one product, how they link, how a document is decided, and where Atlas comes in. What runs today and what is in development.
Decisions holds three kinds of documents for each system you run: what it is for, what was
decided, and what should change. It is the console product that used to be called RFCs; the
console's /rfcs/ addresses send you to /decisions/. The API is /v1/decisions/... with the
scopes decisions:read and decisions:write, the MCP tools are decisions_*, and the command line is
iohr decisions; your data keeps its ids.
Early access
Decisions opens to partners and the platform's admins first, like every product InOrbit is still building. The parts marked in development below are not built yet.
The three kinds
| Kind | Says | What it holds |
|---|---|---|
| PRD | What and why | What a product is for, who uses it, what it must do and how success is measured. No design. |
| RFC | What should change | A proposal: the problem, the design, the alternatives and the slices it ships in. |
| ADR | What was decided | One decision, its context and its consequences. An accepted ADR is never edited; a later one supersedes it. |
Each kind has its own template and checks, and numbers run per kind across an account's spaces, so PRD 0001 and RFC 0001 are two documents. Studies (what was measured) sit beside them.
How documents link
Two lines at the top of a text, after the front matter and before the first ## heading,
make the typed links:
Implements: PRD 0001
- **Context documents:** PRD 0001, RFC 0012An RFC names the PRD it implements; an ADR names the documents it was decided in. The
console shows every link on both documents (an RFC lists its PRD, the PRD lists the RFCs that
implement it) and draws them on the decision map: PRDs at the top, RFCs in the middle, ADRs
at the bottom. Any other mention of a document in a text is listed as a mention, without a
type. The API returns mentions both ways on GetDocument (mentions, mentioned_in); the
type of a link is read from the text.
Decision state and review
| Kind | States |
|---|---|
| PRD | draft, in_review, accepted, rejected, superseded |
| RFC | draft, in_review, accepted, rejected, superseded, withdrawn |
| ADR | proposed, accepted, rejected, superseded |
Putting a document in review names who decides and by when; a passed day marks it overdue
and changes nothing else. Accepting it takes the space's approvals on the current version,
and a document whose scope faces outward (customers, partners, the public) also needs the
owner's own approval. How far the work has got (building, in_review for code in review,
partly_live, live, abandoned) is the stage, kept apart from the decision.
Where Atlas comes in
In development
Nothing in this section runs yet. Today Decisions keeps and decides the documents; it does not check them against code or a running system.
Atlas keeps a system in separate worlds and treats a disagreement between them as a finding. Its first version works on four:
| World | What it holds | Where it comes from | Today |
|---|---|---|---|
| Intended | PRDs, service-level targets, expected outcomes | PRDs in Decisions; monitors' targets | Documents live; Atlas in development |
| Decided | RFCs, ADRs, architecture and security policies | Decisions; network policies, gateway rules | Documents live; Atlas in development |
| Implemented | Code, configuration, manifests, declared dependencies | Your repositories, read by your own agent | In development |
| Deployed | Releases, image digests, runtime configuration | Your clusters and hosts, as a scoped snapshot | In development |
What monitors, the gateway and Trails observe comes after these four.
Evidence states. Every statement Atlas writes will carry its state and at least one source: inferred (read from code or docs), confirmed (an owner said so) or measured (seen on the running system). A statement with no source is not written, and when sources disagree Atlas shows both and asks instead of picking one. A model's reading of code is an interpretation, never a measurement.
Contradictions. A contradiction is two worlds that cannot both hold, shown with both sides and the evidence for each. For example, an ADR says a service never reaches the internet and its network policy allows outbound traffic. Atlas is meant to find such a contradiction without being told where to look, and links each document to the code and services it governs.
What runs today
- PRDs, ADRs and RFCs (and studies), each from its template, with its checks.
- Every version kept, comments on any passage, review by named people.
- Decision state per kind, who decides and by when, the stage apart from it, and the owner's approval of outward-facing documents.
- Import from a repository's
docs/prds,docs/adrsanddocs/rfcs, and export back. - The API under
/v1/decisionsandiohr decisions --kind prd|adr|rfc. - Typed links from
Implements:andContext documents:lines, and the decision map.
In development: Atlas linking documents to code and services, evidence states on its statements, and contradiction detection.