STXT
ESEN .stxt

RFCs and technical proposals

A technical proposal is an argumentative document with a life cycle: it is drafted, discussed, accepted or rejected, and remains as a record of why something was decided. STXT keeps the plain-text, review-based flow these documents already have, and makes the status, the authors and the relations between proposals explicit.

Teams that write technical proposals —internal RFCs, architecture decision records, design documents— usually already do so in plain text and in a repository: the document is reviewed like code, with a diff and comments. What fails is not the flow but the structure: the status of the proposal is a word in the header that each author writes their own way, relations between documents are links in the text, and knowing which proposals are still open or which depend on one that has just been rejected is manual work.

With STXT the proposal is still a text document with long sections, but its header is data. The status is an ENUM, the authors are nodes, references to other proposals are values a program can follow.

A proposal

RFC (com.acme.rfc):
	Id: RFC-013
	Title: Unification of the configuration system
	Status: Review
	Authors:
		Author: Platform Team
	Created: 2026-01-05
	Updated: 2026-01-10

	Context >>
		Several configuration formats coexist today in the internal services,
		each with its own validation rules and its own tooling. Every new team
		picks one, and support has to know them all.

	Proposal >>
		Adopt a single configuration format for internal services, with one
		template per service type maintained by Platform. Existing services migrate
		when they change major version; new ones start with the single format.

	Alternatives:
		Alternative: Keep the current formats
			Pros >>
				No initial cost.
			Cons >>
				Fragmentation remains and grows with every new service.
		Alternative: Standardize on the most widespread format today
			Pros >>
				Tooling and knowledge already present in the teams.
			Cons >>
				Its validation is external and ambiguous; it does not solve the
				underlying problem.

	Impact >>
		Teams migrate gradually. Platform maintains the templates and a validator
		in continuous integration.

	Decision >>
		Under review by the architecture committee.

The header is a block of data: identifier, status, authors and dates. The body is text blocks with the names the organization's process already uses —context, proposal, alternatives, impact, decision—. The alternatives are the most structured part: each one is a node with its title, and its pros and cons are blocks, because that is text that is argued, not data that is counted.

The template

Template (@stxt.template): com.acme.rfc
	Description >>
		RFC: Technical proposal subject to review and decision
		Status: Life cycle of the proposal
		Related: Identifiers of other related proposals
	Structure >>
		RFC:
			Id: (1)
			Title: (1)
			Status: (1) ENUM [Draft, Review, Accepted, Rejected, Deprecated]
			Authors: (1)
				Author: (+)
			Created: (?) DATE
			Updated: (?) DATE
			Accepted date: (?) DATE
			Related: (?)
				Reference: (+)
			Context: (1) TEXT
			Proposal: (1) TEXT
			Alternatives: (?)
				Alternative: (*)
					Pros: (?) TEXT
					Cons: (?) TEXT
			Impact: (?) TEXT
			Risks: (?) TEXT
			Decision: (?) TEXT
			Consequences: (?) TEXT
			Comments: (?)
				Comment: (*)
					Author: (1) @Author
					Date: (1) DATE
					Text: (1) TEXT

The template fixes the minimum every proposal must have —identifier, title, status, at least one author, context and proposal— and leaves the rest optional: a draft may not have alternatives yet, and an accepted one will have a decision and consequences. What it does not do is restrict the text: a TEXT block admits any content and any length.

The Status ENUM is the life cycle of the process. A proposal is neither "pending" nor "approved with remarks": it is in one of five statuses, and changing status is changing one line.

The life cycle in the repository

The same proposal, weeks later, accepted:

RFC (com.acme.rfc):
	Id: RFC-013
	Title: Unification of the configuration system
	Status: Accepted
	Authors:
		Author: Platform Team
	Created: 2026-01-05
	Updated: 2026-01-18
	Accepted date: 2026-01-18

	Context >>
		Several configuration formats coexist today in the internal services,
		each with its own validation rules and its own tooling.

	Proposal >>
		Adopt a single configuration format for internal services, with one
		template per service type maintained by Platform.

	Decision >>
		Gradual adoption is approved. Platform publishes the templates before the
		end of the quarter.

	Consequences >>
		New services use the single format from their creation. Existing ones
		migrate in their next major version, with no deadline.

	Comments:
		Comment:
			Author: Mery Adams
			Date: 2026-01-12
			Text >>
				Concerned about the impact on teams with their own tooling. I propose
				that the migration of existing services has no deadline.
		Comment:
			Author: Keyla Brown
			Date: 2026-01-13
			Text >>
				Agreed on gradual adoption provided Platform maintains the
				templates.

Between the two versions, the diff shows exactly what changed: the status, the acceptance date, the decision, the consequences and two comments. The review comments are stored in the document itself, with author and date, separate from the main text; the discussion stays next to the decision, where someone will look for it two years from now.

Relations between proposals

A proposal that depends on another declares it as data, not only as a sentence:

RFC (com.acme.rfc):
	Id: RFC-020
	Title: Retirement of the previous configuration system
	Status: Draft
	Authors:
		Author: Joan Costa
	Related:
		Reference: RFC-013
		Reference: RFC-007

	Context >>
		With the adoption of the single format (RFC-013), the previous system has
		no new services and a growing maintenance cost.

	Proposal >>
		Retire the previous system once the services still using it have
		migrated.

With Related as a node, a program walking the proposals directory can answer what depends on what, which drafts cite a rejected proposal, or draw the whole graph. With the reference only in the context text, none of those questions can be answered without reading.

In the workflow

  • Proposals live in a directory of the repository, one per file, with the template in .stxt/.
  • Continuous integration runs stxt validate rfcs/ (The command line) on every change: a proposal without context or with a status outside the list does not get in.
  • A script over the canonical tree generates the index of proposals by status, warns about those that have been in Review for more than a month, or lists the consequences of all the ones accepted in the quarter.
  • The text of each section is published as is, in whatever format the organization uses for its documentation.

Limits

STXT imposes no process: section names, statuses and who may change them are decisions of each organization, and the template only records them. Nor does it replace the review tool: the comments in the example are the record of the discussion, not a threading system with notifications. And validation does not check relations between documents —that RFC-007 exists, that an accepted proposal does not cite a rejected one—: that is done by the script that walks the directory.

Minutes and status reports, the neighbouring genre, are developed in Corporate documents; the tutorial covers the language behind the examples.