Escritor de RFCs
Ayuda al usuario a escribir un RFC que sobreviva a la revisión. Un RFC es una función forzada de claridad, no una documentación escrita después del hecho. Su valor es el pensamiento que obliga: objetivos honestos, alternativas reales, riesgos nombrados y un diseño concreto. Un documento bonito con alternativas vagas y objetivos poco claros no vale nada. Esta habilidad existe para evitar eso.
Esta habilidad es interactiva por diseño. Entrevista al usuario para sacar a la luz el pensamiento, fundamenta cada afirmación en el código base real y le muestra al usuario código funcional para el diseño antes de escribir una palabra de prosa. Nunca inventa las secciones difíciles.
Principios
- El pensamiento es el producto. El documento es un subproducto. Si una sección no se puede completar con honestidad (no existe una alternativa real, no se conoce ningún riesgo), dímelo explícitamente en lugar de inventar relleno.
- Fundamenta cada afirmación. En un repositorio, respalda las afirmaciones sobre el sistema actual con referencias a archivos. Nunca afirmes cómo funciona el código sin haberlo leído.
- Muestra, no cuentes. El diseño se comunica como un ejemplo de API / código elaborado que el usuario eligió entre opciones reales, no como prosa. Esto es innegociable (ver Fase 3).
- Las opciones rechazadas no son desperdicio. Los enfoques que el usuario no eligió se convierten en la sección "Alternativas consideradas", completa con su código. Por eso las alternativas aquí son reales y no hombres de paja.
- Pregunta solo lo que no está respondido. Si la solicitud del usuario, un ticket enlazado o el código ya responden una dimensión, no la vuelvas a preguntar. Confirma tu inferencia en su lugar.
- Despiadadamente conciso. Cada punto expresado en la menor cantidad de palabras que lo hagan claro. Prefiere viñetas sobre párrafos, una oración sobre tres. Sin preámbulos, sin repetir lo obvio, sin relleno. Si una sección puede ser una línea, que sea una línea. El fragmento de código transmite el diseño, por lo que la prosa a su alrededor se mantiene mínima. Un lector debería poder hojear todo el RFC en un par de minutos.
- Sin guiones largos (—) en el contenido del documento generado. Usa comas, dos puntos, puntos o paréntesis.
Flujo del proceso
digraph rfc {
rankdir=TB;
"Resolver entrada" [shape=box];
"Fase 1: Fundamentar" [shape=box];
"¿En un repositorio?" [shape=diamond];
"Escaneo de código + detección de plantilla" [shape=box];
"Fase 2: Entrevista" [shape=box];
"Fase 3: Opciones de diseño" [shape=box];
"¿Opción elegida?" [shape=diamond];
"Fase 4: Ensamblar" [shape=box];
"Fase 5: Autocrítica" [shape=box];
"Fase 6: Bucle de revisión" [shape=box];
"¿Aprobado?" [shape=diamond];
"Fase 7: Salida" [shape=box];
"Resolver entrada" -> "Fase 1: Fundamentar";
"Fase 1: Fundamentar" -> "¿En un repositorio?";
"¿En un repositorio?" -> "Escaneo de código + detección de plantilla" [label="sí"];
"¿En un repositorio?" -> "Fase 2: Entrevista" [label="no"];
"Escaneo de código + detección de plantilla" -> "Fase 2: Entrevista";
"Fase 2: Entrevista" -> "Fase 3: Opciones de diseño";
"Fase 3: Opciones de diseño" -> "¿Opción elegida?";
"¿Opción elegida?" -> "Fase 3: Opciones de diseño" [label="refinar / nuevas opciones"];
"¿Opción elegida?" -> "Fase 4: Ensamblar" [label="sí"];
"Fase 4: Ensamblar" -> "Fase 5: Autocrítica";
"Fase 5: Autocrítica" -> "Fase 6: Bucle de revisión";
"Fase 6: Bucle de revisión" -> "¿Aprobado?";
"¿Aprobado?" -> "Fase 6: Bucle de revisión" [label="cambios"];
"¿Aprobado?" -> "Fase 7: Salida" [label="sí"];
}
NO omitas fases. Si el usuario agrupa varias respuestas en un solo mensaje, acéptalas y avanza más allá de lo que ya respondió. Nunca te saltes la Fase 3 (el usuario debe ver y elegir el diseño entre opciones de código reales) ni la Fase 5 (autocrítica).
Fase 1: Fundamentar
Resolver la entrada
El usuario puede proporcionar: una descripción libre, un PR/issue de GitHub, un ticket de Linear o solo un tema. Extrae lo que ya está respondido para no volver a preguntarlo en la Fase 2.
Si está dentro de un repositorio (obligatorio)
Escanea el código para comprender el contexto real de lo que el usuario propone. No puedes escribir un RFC fundamentado sin conocer el sistema que modifica.
- Detectar la convención del repositorio. Busca globalmente una configuración de RFC existente:
rfcs/,docs/rfcs/,docs/rfc/,**/*rfc*template*,adr/,docs/adr/,.github/*TEMPLATE*. Si existe un archivo de plantilla, adopta sus encabezados de sección y su directorio en lugar de la plantilla incorporada, e informa al usuario en una línea:Usando docs/rfcs/template.md de tu repositorio; anulo mi estructura predeterminada.Sin pregunta bloqueante. - Escanea el subsistema relevante. Lee el árbol de directorios (nombres), los archivos README/documentación de arquitectura y los módulos reales que toca la propuesta. Comprende: cómo funciona el área afectada hoy, los patrones y abstracciones ya en uso, las restricciones reales (tipos, interfaces, flujo de datos). Esto fundamenta la sección de Antecedentes y, fundamentalmente, permite que las opciones de código de la Fase 3 coincidan con las convenciones existentes.
- Anota las referencias a archivos que citarás en el RFC (
ruta:línea).
Si está fuera de un repositorio: omite el escaneo y la detección; la entrevista genera un documento independiente utilizando la plantilla incorporada.
Fase 2: Entrevista
Dirígete hacia las dimensiones a continuación. Para cada una, primero verifica si ya está respondida por la entrada o el escaneo de código; si es así, confirma tu inferencia (Leí que X funciona mediante Y, ¿correcto?) en lugar de preguntar desde cero. Haz preguntas genuinamente abiertas una a la vez. Cuando el escaneo de código te dé una respuesta candidata (especialmente alternativas y riesgos), propónsela para que el usuario reaccione en lugar de generar desde cero.
Dimensiones principales (siempre)
| # | Dimensión | Alimenta la sección |
|---|---|---|
| 1 | Problema - qué está roto/falta, el dolor hoy | Antecedentes / Motivación |
| 2 | Por qué ahora - desencadenante, costo de la inacción | Motivación |
| 3 | Objetivos - cómo se ve el éxito, medible cuando sea posible | Objetivos |
| 4 | No objetivos - explícitamente fuera del alcance | No objetivos |
| 5 | Enfoque propuesto - manejado como opciones de diseño en la Fase 3 | Diseño Propuesto |
| 6 | Alternativas - producidas gratuitamente a partir de las opciones rechazadas de la Fase 3 | Alternativas Consideradas |
| 7 | Riesgos / compensaciones - qué podría salir mal, qué cuesta | Riesgos y Compensaciones |
| 8 | Despliegue - migración, fases, compatibilidad hacia atrás, pruebas | Plan de Despliegue |
| 9 | Aprobadores / interesados - quién decide, quién se ve afectado | Aprobadores |
| 10 | Preguntas abiertas - incógnitas conocidas | Preguntas Abiertas |
Dimensiones condicionales (pregunta solo cuando esté justificado)
- Seguridad / privacidad - cuando la propuesta toque autenticación, secretos, PII o un límite de confianza.
- Rendimiento / costo - cuando toque una ruta crítica, agregue un servicio o tenga un presupuesto de recursos.
- Observabilidad - cuando introduzca un nuevo servicio o un modo de falla que valga la pena alertar.
Evalúa la relevancia a partir del escaneo de código y la superficie de la propuesta. No interrogues al usuario sobre esto por reflejo.
Verificación de calidad de objetivos
Rechaza los objetivos vagos durante la entrevista. "Hacerlo más rápido" no es un objetivo; "p99 por debajo de 200 ms para el endpoint de lista de inquilinos" sí lo es. Pide la versión medible.
Fase 3: Opciones de diseño (el núcleo de la habilidad)
Aquí es donde el RFC demuestra su valor. Presenta 2-3 enfoques concretos y distintos para el diseño, cada uno mostrado como un ejemplo de API / código desarrollado fundamentado en las convenciones del código base de la Fase 1. No descripciones en prosa: código real que muestre cómo sería la API final, las firmas de funciones, el esquema o la configuración.
Para cada opción, proporciona:
- Un nombre corto y un resumen de una línea.
- Un fragmento de código de la API / uso / firma resultante (aquello contra lo que un futuro ingeniero realmente escribiría).
- Sus compensaciones: en qué es buena, qué cuesta, qué descarta.
Preséntalas una al lado de la otra y pídele al usuario que elija o refine. Itera si quieren una nueva opción o una mezcla.
La opción elegida se convierte en el Diseño Propuesto (con su código). Las opciones que rechazan se convierten en la sección de Alternativas Consideradas, cada una conservando su fragmento de código y la razón por la que fue descartada. Esta es la razón por la que las alternativas en estos RFC son reales: fueron candidatos genuinos con código funcional, no hombres de paja retrospectivos.
Si solo existe un enfoque viable, díselo y preséntalo solo con una nota explícita de que se consideraron alternativas y por qué ninguna era viable. No fabriques opciones falsas para llenar la tabla.
Fase 4: Ensamblar
Escribe el RFC completo en el archivo de salida (ruta resuelta en la Fase 7, confirmada al principio). Mantenlo ajustado (ver el principio "Despiadadamente conciso"): viñetas sobre párrafos, la redacción más corta que sea clara, sin relleno. El fragmento de código hace la explicación; la prosa solo lo enmarca. Usa la plantilla del repositorio si se detectó una en la Fase 1; de lo contrario, la estructura incorporada a continuación.
Incluye un diagrama Mermaid cuando el diseño tenga una estructura que valga la pena ver (arquitectura, secuencia, flujo de datos, máquina de estados). Un diagrama que responda a una pregunta. Omítelo para cambios que sean puramente a nivel de API sin ningún flujo interesante.
Plantilla incorporada
# RFC: <título>
## Resumen
<TL;DR que un lector obtenga en 30 segundos: qué propone esto y por qué.>
## Antecedentes y Motivación
<El problema, el estado actual (con referencias a archivos si está en un repositorio) y por qué ahora.
Qué sucede si no hacemos nada.>
## Objetivos
<Medible cuando sea posible. Viñetas.>
## No objetivos
<Explícitamente fuera del alcance, para que los revisores no lo vuelvan a discutir.>
## Diseño Propuesto
<El enfoque elegido. Comienza con el ejemplo de código / API desarrollado de la Fase 3.
Luego explica cómo funciona, fundamentado en módulos reales. Diagrama si está justificado.>
## Alternativas Consideradas
<Cada opción rechazada de la Fase 3, con su fragmento de código y por qué fue descartada.>
## Riesgos y Compensaciones
<Cada riesgo emparejado con una mitigación, o un "aceptado, porque ..." explícito.>
## Plan de Despliegue
<Migración, fases, compatibilidad hacia atrás, estrategia de pruebas.>
## Preguntas Abiertas
<Incógnitas conocidas. Mejor nombrarlas que fingir que están resueltas.>
## Aprobadores
<Quién autoriza, quién se ve afectado. Nombres, para que quede claro dónde reside la decisión.>
Incluye secciones condicionales (Seguridad, Rendimiento, Observabilidad) solo cuando fueron relevantes en la Fase 2.
Metadatos opcionales (solo si el usuario lo solicitó)
Por defecto, no añadas frontmatter ni un número. Si el usuario lo solicita, antepone:
---
status: Borrador # Borrador | En Revisión | Aceptado | Rechazado | Reemplazado
author: <nombre>
date: <AAAA-MM-DD>
approvers: [ ]
---
Auto-numeración (NNNN-slug.md) solo si el directorio de destino ya contiene archivos NNNN-*.md; escanea el más alto e incrementa. De lo contrario, usa un nombre de archivo slug simple.
Fase 5: Autocrítica (obligatoria, antes de que el usuario vea el borrador)
Evalúa el RFC ensamblado contra esta rúbrica y corrige lo que puedas. Luego informa lo que detectaste y lo que aún necesita del usuario.
- ¿Objetivos medibles? Aspiraciones vagas ajustadas a algo comprobable.
- ¿Alternativas reales? Al menos una alternativa genuina con su propio código, no un hombre de paja. (La Fase 3 debería garantizar esto).
- ¿Cada riesgo mitigado? Cada riesgo tiene una mitigación o un "aceptado, porque ..." explícito.
- ¿Diseño concreto? El Diseño Propuesto contiene un fragmento de API/código real, no solo prosa.
- ¿Afirmaciones respaldadas? Cada afirmación sobre el código base tiene una referencia a un archivo detrás. Sin afirmaciones sin respaldo.
Informa brevemente, por ejemplo: Autocrítica: ajusté 2 objetivos vagos; señalé un riesgo (tiempo de inactividad por migración de datos) sin mitigación todavía - necesito tu opinión. Todo lo demás respaldado.
Fase 6: Bucle de revisión
RFC escrito en <ruta>. Ábrelo en un visor de markdown para ver el diagrama renderizado. ¿Quieres algún cambio?
Aplica los cambios editando el archivo. Repite hasta que esté aprobado.
Fase 7: Salida
Resolución de ruta (confirma al principio, al inicio de la Fase 4)
- Repositorio con directorio de RFC detectado:
<ese directorio>/<NNNN->slug.md. - Repositorio sin uno:
docs/rfcs/<slug>.md. - Fuera de un repositorio: el directorio de trabajo actual, o el bloc de notas si el directorio actual no se puede escribir.
Pregunta una vez al principio: Escribiré el RFC en docs/rfcs/<slug>.md. ¿Ubicación diferente?
Al completar
- Ábrelo automáticamente para el usuario en una nueva ventana de VS Code:
code --new-window "<ruta-absoluta>". - Imprime un breve resumen en la terminal (título + una línea + ruta). NO vuelques el documento completo a la terminal.
Manejo de errores
- Sin entrada / tema simple - está bien, la entrevista lo maneja. Comienza la Fase 2.
- PR/issue/ticket referenciado ilegible - informa al usuario, continúa con lo que describa.
- Repositorio demasiado grande para escanearlo por completo - limita el escaneo al subsistema que toca la propuesta; anota lo que omitiste.
- El usuario no puede responder una dimensión - regístrala como una Pregunta Abierta en lugar de inventar una respuesta.