RFCs y propuestas técnicas

Una propuesta técnica es un documento argumentativo con un ciclo de vida: se redacta, se discute, se acepta o se rechaza, y queda como registro de por qué se decidió algo. STXT conserva el flujo de texto plano y revisión que estos documentos ya tienen, y hace explícitos el estado, los autores y las relaciones entre propuestas.

Los equipos que escriben propuestas técnicas —RFC internos, registros de decisiones de arquitectura, documentos de diseño— suelen hacerlo ya en texto plano y en un repositorio: el documento se revisa como el código, con un diff y comentarios. Lo que falla no es el flujo sino la estructura: el estado de la propuesta es una palabra en la cabecera que cada autor escribe a su manera, las relaciones entre documentos son enlaces en el texto, y saber qué propuestas siguen abiertas o cuáles dependen de una que se acaba de rechazar es un trabajo manual.

Con STXT la propuesta sigue siendo un documento de texto con secciones largas, pero su cabecera son datos. El estado es un ENUM, los autores son nodos, las referencias a otras propuestas son valores que un programa puede seguir.

Una propuesta

RFC (com.acme.rfc):
	Id: RFC-013
	Title: Unificación del sistema de configuración
	Status: Review
	Authors:
		Author: Platform Team
	Created: 2026-01-05
	Updated: 2026-01-10

	Context >>
		Hoy conviven varios formatos de configuración en los servicios internos,
		cada uno con sus propias reglas de validación y sus propias herramientas.
		Cada equipo nuevo elige uno, y el soporte tiene que conocerlos todos.

	Proposal >>
		Adoptar un único formato de configuración para los servicios internos, con
		una plantilla por tipo de servicio mantenida por Plataforma. Los servicios
		existentes migran cuando cambien de versión mayor; los nuevos arrancan ya con
		el formato único.

	Alternatives:
		Alternative: Mantener los formatos actuales
			Pros >>
				Sin coste inicial.
			Cons >>
				La fragmentación se mantiene y crece con cada servicio nuevo.
		Alternative: Estandarizar en el formato más extendido hoy
			Pros >>
				Herramientas y conocimiento ya existentes en los equipos.
			Cons >>
				Su validación es externa y ambigua; no resuelve el problema de fondo.

	Impact >>
		Los equipos migran gradualmente. Plataforma mantiene las plantillas y un
		validador en integración continua.

	Decision >>
		En revisión por el comité de arquitectura.

La cabecera es un bloque de datos: identificador, estado, autores y fechas. El cuerpo son bloques de texto con los nombres que el proceso de la organización ya usa —contexto, propuesta, alternativas, impacto, decisión—. Las alternativas son la parte más estructurada: cada una es un nodo con su título, y sus pros y contras son bloques, porque es texto que se argumenta, no datos que se cuentan.

La plantilla

Template (@stxt.template): com.acme.rfc
	Description >>
		RFC: Propuesta técnica sujeta a revisión y decisión
		Status: Ciclo de vida de la propuesta
		Related: Identificadores de otras propuestas relacionadas
	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

La plantilla fija lo mínimo que toda propuesta debe tener —identificador, título, estado, al menos un autor, contexto y propuesta— y deja el resto opcional: una propuesta en borrador puede no tener alternativas todavía, y una aceptada tendrá decisión y consecuencias. Lo que no hace es restringir el texto: un bloque TEXT admite cualquier contenido y cualquier longitud.

El ENUM de Status es el ciclo de vida del proceso. Una propuesta no está «pendiente» ni «aprobada con matices»: está en uno de cinco estados, y cambiar de estado es cambiar una línea.

El ciclo de vida en el repositorio

La misma propuesta, semanas después, aceptada:

RFC (com.acme.rfc):
	Id: RFC-013
	Title: Unificación del sistema de configuración
	Status: Accepted
	Authors:
		Author: Platform Team
	Created: 2026-01-05
	Updated: 2026-01-18
	Accepted date: 2026-01-18

	Context >>
		Hoy conviven varios formatos de configuración en los servicios internos,
		cada uno con sus propias reglas de validación y sus propias herramientas.

	Proposal >>
		Adoptar un único formato de configuración para los servicios internos, con
		una plantilla por tipo de servicio mantenida por Plataforma.

	Decision >>
		Se aprueba la adopción progresiva. Plataforma publica las plantillas antes
		del fin del trimestre.

	Consequences >>
		Los servicios nuevos usan el formato único desde su creación. Los existentes
		migran en su siguiente versión mayor, sin fecha límite.

	Comments:
		Comment:
			Author: Mery Adams
			Date: 2026-01-12
			Text >>
				Preocupa el impacto en los equipos con herramientas propias. Propongo
				que la migración de los servicios existentes no tenga fecha límite.
		Comment:
			Author: Keyla Brown
			Date: 2026-01-13
			Text >>
				De acuerdo con la adopción progresiva si Plataforma mantiene las
				plantillas.

Entre las dos versiones, el diff muestra exactamente qué cambió: el estado, la fecha de aceptación, la decisión, las consecuencias y dos comentarios. Los comentarios de la revisión se guardan en el propio documento, con autor y fecha, separados del texto principal; la discusión queda junto a la decisión, donde alguien la buscará dentro de dos años.

Relaciones entre propuestas

Una propuesta que depende de otra lo declara como dato, no solo como una frase:

RFC (com.acme.rfc):
	Id: RFC-020
	Title: Retirada del sistema de configuración anterior
	Status: Draft
	Authors:
		Author: Joan Costa
	Related:
		Reference: RFC-013
		Reference: RFC-007

	Context >>
		Con la adopción del formato único (RFC-013), el sistema anterior queda
		sin servicios nuevos y con coste de mantenimiento creciente.

	Proposal >>
		Retirar el sistema anterior una vez migrados los servicios que aún lo usan.

Con Related como nodo, un programa que recorra el directorio de propuestas puede responder qué depende de qué, qué propuestas en borrador citan una rechazada, o dibujar el grafo entero. Con la referencia solo en el texto del contexto, ninguna de esas preguntas se puede responder sin leer.

En el flujo de trabajo

Las propuestas viven en un directorio del repositorio, una por fichero, con la plantilla en .stxt/.
Integración continua ejecuta stxt validate rfcs/ (La línea de comandos) en cada cambio: una propuesta sin contexto o con un estado fuera de la lista no entra.
Un script sobre el árbol canónico genera el índice de propuestas por estado, avisa de las que llevan más de un mes en Review o lista las consecuencias de todas las aceptadas del trimestre.
El texto de cada sección se publica tal cual, en el formato que la organización use para su documentación.

Límites

STXT no impone un proceso: los nombres de las secciones, los estados y quién puede cambiarlos son decisiones de cada organización, y la plantilla solo las recoge. Tampoco sustituye a la herramienta de revisión: los comentarios del ejemplo son el registro de la discusión, no un sistema de hilos con notificaciones. Y la validación no comprueba relaciones entre documentos —que RFC-007 exista, que una propuesta aceptada no cite una rechazada—: eso lo hace el script que recorre el directorio.

Las actas y los informes de estado, el género vecino, se desarrollan en Documentos corporativos; el tutorial recorre el lenguaje que hay detrás de los ejemplos.