Al terminar esta lección
- Elegir la plantilla correcta según la pregunta que tenés que responder, no según el artefacto que te parece más formal.
- Completar cada plantilla con fuentes, autoridad y estado, sin dejar campos que parezcan resueltos cuando no lo están.
- Detectar en una plantilla llena los defectos típicos: una regla sin autoridad, un estado que contradice la evidencia o un valor inventado.
- Armar la matriz de trazabilidad que conecta evidencia, regla, decisión, código y prueba.
- Reconocer cuándo una plantilla se convirtió en un formulario vacío que nadie lee.
Antes de copiar una plantilla
Una plantilla es un andamio para que las preguntas obligatorias no se olviden. No reemplaza el trabajo de descubrirlas. Un campo vacío se completa con DESCONOCIDO o BLOCKED, nunca con un valor plausible. Un campo "Autoridad" con "el equipo" o "se habló en la reunión" no es una autoridad.
Las plantillas están pensadas para dos lectores: un humano que tiene que discutirlas en una reunión, y un agente que va a recibirlas como contexto. Si una plantilla no le sirve a alguno de los dos, sobra.
Elegí la plantilla por la pregunta que responde:
Apéndice B · Plantillas mínimas reutilizables
B.1 Registro de evidencia
Cómo completarla: un registro por observación. El tipo tiene que ser el que describe la fuente, no el que te conviene. Si la descripción contiene un juicio ("el cliente es desprolijo"), reescribila como hecho observable. El campo "Pregunta siguiente" tiene una sola pregunta. Las reglas no son un tipo de evidencia: van a la plantilla B.2 (RN).
EV-__
Tipo: HECHO | DECLARACIÓN | HIPÓTESIS | DESCONOCIDO | DECISIÓN
Fuente / propietario:
Fecha / contexto:
Descripción observable:
Impacto potencial:
Pregunta siguiente:
Artefactos afectados:
Ejemplo mínimo de Nexo:
EV-02
Tipo: HECHO
Fuente / propietario: pedido 48172 y hoja auxiliar de equivalencias de la vendedora, mostrados en la reunión 1
Fecha / contexto: pedido del jueves, recibido a las 10:02
Descripción observable: el pedido pide A-184 y la vendedora lo reemplazó por A-184B usando una hoja auxiliar.
Impacto potencial: el precio y la disponibilidad dependen de la equivalencia vigente en la fecha del pedido.
Pregunta siguiente: ¿quién mantiene la hoja y desde qué fecha rige cada equivalencia?
Artefactos afectados: RN-04, 02-incertidumbre/plan-investigacion.yaml
B.2 Regla de negocio
Cómo completarla: la condición tiene que ser verificable con datos, sin "cuando sea razonable". El resultado describe qué pasa en el sistema. La autoridad es una persona o un documento con nombre, no "la política". Si no podés llenar "Ejemplo frontera", la regla todavía no está entendida. El estado BLOCKED se usa cuando falta la decisión o el valor, aunque la regla esté bien pensada en lo demás.
RN-__ Nombre corto
Condición:
Resultado:
Autoridad / fuente:
Ejemplo normal:
Ejemplo frontera:
Excepción autorizable:
Estado: confirmada | provisional | BLOCKED
Ejemplo mínimo de Nexo, completo:
RN-01 Límite de crédito del cliente estándar
Condición: el cliente es ESTÁNDAR y saldoDeudor + totalPedido supera limiteCredito.
Resultado: el pedido no se confirma por crédito; no queda reserva firme.
Autoridad / fuente: política de crédito vigente, Laura (administración y crédito).
Ejemplo normal: saldo 480.000 + pedido 15.000 = 495.000, con límite 500.000: confirma.
Ejemplo frontera: saldo 480.000 + pedido 20.000 = 500.000: permitido. Con un centavo más, rechaza.
Excepción autorizable: sí, por CU-02 (desde el módulo 5), con motivo y auditoría. No cambia el límite permanente.
Estado: confirmada
Antes de seguir, revisá este borrador de RN-02. Tiene cuatro defectos. Hacé clic en las líneas que están mal.
Encontrá los defectos de la RN-02
Hacé clic en las líneas con problemas. Hay cuatro. Pensá en qué tendría que decir una regla BLOCKED.
B.3 Caso de uso
Cómo completarla: el objetivo se escribe como resultado observable para el actor ("registrar un pedido con precio autorizado"), no como una pantalla ("formulario de pedido"). Los alternativos tienen condición observable. Las garantías describen ausencia o presencia de efectos: qué no puede quedar en la base aunque falle algo. Los criterios de aceptación se referencian por ID (AC-xx), no se escriben repetidos.
CU-__ Nombre orientado a objetivo
Actor primario:
Objetivo:
Disparador:
Precondiciones:
Curso principal:
Alternativos / excepciones:
Garantía mínima:
Garantía de éxito:
RN/NFR:
Criterios de aceptación:
Ejemplo mínimo de Nexo:
CU-02 Autorizar excepción de crédito
Actor primario: Responsable de crédito (Laura)
Objetivo: resolver un pedido en PENDIENTE_AUTORIZACION con una decisión registrada y motivada.
Disparador: CU-01 deja el pedido pendiente por crédito.
Precondiciones: el pedido existe en estado PENDIENTE_AUTORIZACION; el actor tiene permiso separado para autorizar.
Curso principal: 1) el actor ve saldo, límite y motivo del bloqueo; 2) registra el motivo; 3) autoriza; 4) el pedido pasa a CONFIRMADO y la reserva blanda se vuelve firme.
Alternativos / excepciones: rechaza y el pedido queda CANCELADO; el actor no tiene permiso, rechaza la operación.
Garantía mínima: sin motivo registrado no hay autorización; el límite permanente del cliente no cambia.
Garantía de éxito: existe una decisión auditada con actor, instante, regla aplicada, pedido y motivo.
RN/NFR: RN-01, RN-07 (BLOCKED en el TTL), NFR-02.
Criterios de aceptación: AC-08.
B.4 ADR
Cómo completarla: un ADR responde por qué se eligió algo y qué lo haría cambiar. Si "Opciones consideradas" tiene una sola opción, no hubo decisión, hubo costumbre. "Evidencia / experimento" tiene que apuntar a una prueba o medición que existe o que está planificada. "Disparador de revisión" es una condición observable, no "cuando crezca".
ADR-__ Título
Estado:
Contexto / ASR:
Opciones consideradas:
Decisión:
Consecuencias positivas:
Consecuencias negativas:
Evidencia / experimento:
Disparador de revisión:
Ejemplo mínimo de Nexo:
ADR-002 PostgreSQL como fuente transaccional de stock y reserva
Estado: aceptado
Contexto / ASR: dos pedidos no pueden prometer la misma última unidad (AC-06, RN-05).
Opciones consideradas: contadores en Redis; cola de reservas; actualización condicional en PostgreSQL dentro de la transacción del pedido.
Decisión: actualización condicional en PostgreSQL, con la reserva en la misma transacción que el pedido.
Consecuencias positivas: consistencia local, sin dependencias nuevas, un solo lugar de auditoría.
Consecuencias negativas: el límite de escala lo marca la base; hay que cuidar índices y tiempos de transacción.
Evidencia / experimento: prueba de integración concurrente con dos reservas sobre una unidad (T06).
Disparador de revisión: contención medida en la base que supere el NFR-01 con la carga acordada.
B.5 Sprint de Arquitectura
Cómo completarla: es un índice, no un documento para llenar de una vez. Cada sección responde a una decisión; si una sección no tiene decisiones, se escribe "no aplica, por qué". Los puntos 3, 14 y 18 son los que más se omiten y los que más piden los clientes.
1. Contexto y problema
2. Objetivos y métricas
3. Fuera de alcance / BLOCKED
4. Stakeholders, actores y casos principales
5. RN, NFR y ASR
6. Dominio y autoridad de datos
7. Decisiones arquitectónicas / ADR
8. Componentes y persistencia
9. Integraciones y fallos
10. Seguridad / auditoría
11. Concurrencia / consistencia / idempotencia
12. Observabilidad
13. Despliegue y migraciones
14. Riesgos y unknowns
15. Estrategia de pruebas
16. Criterios de aceptación
17. Implementación incremental
18. Specification Bundle por slice
B.6 Dossier de discovery
Cómo completarla: el dossier es el mapa del proyecto en una sola vista. Las afirmaciones se registran con el origen, no con la verdad: una afirmación del brief sigue siendo afirmación hasta que aparezca un hecho que la confirme. Los desconocidos siempre tienen dueño y fecha. Si el dossier no tiene desconocidos, es señal de que todavía no lo revisaste.
proyecto: Nexo B2B
version: 0.3
objetivo_discovery: "Entender cómo nace, se valida, se prepara y se cierra un pedido mayorista."
fuentes:
- id: FU-01
tipo: brief
detalle: "Mensaje inicial de la dueña, sin editar"
afirmaciones:
- id: AF-01
texto: "El ERP ya tiene los productos y los precios."
origen: FU-01
estado: DECLARACIÓN
evidencia_pendiente: "Confirmar si los precios que cobra cada cliente salen del ERP o de otra fuente."
contexto_publico: # lo que cualquiera puede ver; no es evidencia del proceso interno
- id: DOS-01
senal: "La web anuncia «más de 8.000 productos»."
fuente: "sitio web, página de inicio"
abre: "¿Todo el catálogo está en el ERP? ¿Quién lo mantiene?"
desconocidos:
- id: U-01
pregunta: "¿Cómo se calcula la exposición de crédito de un cliente?"
dueno: "Laura (administración y crédito)"
fecha_respuesta: "A confirmar en la segunda reunión"
bloquea: "CU-01 paso 6 (evaluar crédito)"
hipotesis:
- id: HIP-01
texto: "Parte de las unidades figuran como disponibles en el ERP pero ya están reservadas a mano, sin registro en el sistema."
refutable_con: "Comparar ERP, pizarra y pedidos abiertos de tres días."
Ejemplo de uso: si un desarrollador lee el dossier, tiene que poder decir qué afirmaciones están confirmadas y cuáles no, sin abrir el brief.
B.7 Minuta de reunión
Cómo completarla: la minuta registra lo que pasó, no lo que hubiera sido ideal. Los episodios van antes que las conclusiones. Cada decisión tiene autoridad y cada pendiente tiene dueño y fecha. Si una afirmación del cliente aparece como "acordado" sin decisión escrita, pasala a desconocido.
# Minuta · Reunión N · AAAA-MM-DD
Participantes: nombre y rol de cada uno.
Objetivo de la reunión: una frase.
Episodios revisados: pedido, fecha, qué pasó, quién lo vio.
Hechos (H): lo observado, con fuente.
Declaraciones (D): lo que alguien dijo, con quién lo dijo.
Desconocidos (?): pregunta, dueño, fecha de respuesta.
Decisiones (DEC): decisión, autoridad, alternativa descartada.
Próximos pasos: qué, quién, cuándo.
Playback: fecha de envío.
Ejemplo mínimo de Nexo:
# Minuta · Reunión 1 · 2026-10-16
Participantes: Marta (dueña), la vendedora, un operario de depósito y el Responsable del Desarrollo, que conduce. Laura (administración y crédito) se suma por videollamada cerca del minuto 10. Ausente relevante: el responsable comercial.
Objetivo: reconstruir cómo llegó y cómo se corrigió el pedido 48172.
Episodios revisados: pedido 48172 del jueves 2026-10-15, recibido por WhatsApp a las 10:02, con 23 códigos.
Hechos (H): Laura compartió pantalla y mostró la planilla de cheques pendientes que consultó para el 48172 (observado en la reunión); la aprobación del 48172 es un audio de Laura (documentado).
Declaraciones (D): la vendedora relató que el saldo superó el límite a las 10:11 y que depósito avisó el faltante de AX-442 a las 10:31. Marta dijo que el crédito se controla en el ERP; la planilla de cheques que mostró Laura indica otra cosa.
Desconocidos (?): cuánto tiempo puede estar reservado el stock de un pedido pendiente. Dueño: Sergio (depósito) y comercial. Fecha: próxima reunión.
Decisiones (DEC): ninguna. El punto de la reserva queda BLOCKED.
Próximos pasos: el Responsable del Desarrollo pide al operario el registro del quiebre de la última semana.
Playback: enviado dentro de las 24 horas.
B.8 Glosario de dominio
Cómo completarla: un término por entrada, con la definición que usa el proyecto, y un campo "no confundir con" para las colisiones. El glosario crece con las reuniones; si una palabra aparece con dos significados en las notas, es una entrada nueva, no una corrección silenciosa.
terminos:
- termino: Disponible
definicion: "onHand menos reserved, por depósito y SKU. Nunca negativo."
no_confundir_con: "Stock del ERP, que no registra reservas."
- termino: Quiebre físico
definicion: "Diferencia entre el stock registrado y el que hay en el estante."
no_confundir_con: "Carrera digital: dos pedidos compiten por una unidad en el sistema."
- termino: Pedido confirmado
definicion: "Aceptado comercialmente. Su significado para depósito es otro: ya impreso y con stock verificado."
no_confundir_con: "Pedido listo para preparar. Se usan estados distintos si hace falta."
B.9 Requerimientos funcionales y no funcionales
Cómo completarla: un RF describe una capacidad del sistema y se conecta a una RN o a un objetivo. Un NFR tiene escenario, medición y umbral. Si el umbral todavía no se midió, la columna dice "a validar con prototipo" y no se inventa la cifra. Un NFR sin escenario ("debe ser rápido") no se puede verificar.
requerimientos_funcionales:
- id: RF-03
descripcion: "El precio de cada línea lo calcula el servidor desde la lista vigente y los acuerdos autorizados."
origen: RN-03
fuera_de_alcance: "El cliente no envía unitPrice autoritativo."
aceptacion: AC-04
requerimientos_no_funcionales:
- id: NFR-01
categoria: latencia
escenario: "Registro de pedido, p95 menor a 800 ms, con 30 usuarios concurrentes y dataset representativo."
medicion: "Prueba de carga con rampa de 2 minutos y 10 minutos estables."
estado: "Umbral a validar con prototipo y operación."
- id: NFR-02
categoria: auditoría
escenario: "Toda autorización de excepción conserva actor, instante, regla, pedido y motivo durante el período acordado."
medicion: "Consulta del audit trail tras una autorización de prueba."
estado: confirmada
B.10 Specification Bundle
Cómo completarla: el bundle es el contexto mínimo para ejecutar un slice. Referencia las RN por ID, no las copia. Tiene que decir quién tiene autoridad sobre cada dato, qué invariantes no se pueden romper, qué queda fuera de alcance y qué gates corren. Si el bundle reproduce el manual entero, falló la selección de contexto; si no menciona los BLOCKED, el agente va a inventarlos.
# Context bundle: <nombre del slice>
Objetivo observable:
<una frase que alguien pueda verificar>
Autoridad:
<dato> -> <fuente que decide>
Contratos focales:
<firma del puerto o del comando>
Invariantes:
- <propiedad que nunca puede romperse>
BLOCKED que el agente no debe resolver:
- <ID y dueño>
Archivos relevantes:
- <ruta>
Fuera de alcance:
- <lista explícita>
Gates:
<comandos que deben pasar>
Ejemplo mínimo de Nexo, con las primeras líneas de un slice de reserva:
# Context bundle: Slice 2 · reserva e idempotencia (alias SLICE-C-RESERVA)
Objetivo observable:
Reservar stock por depósito sin sobreventa al confirmar CU-01.
Autoridad:
Disponibilidad -> onHand menos reserved (RN-05), en PostgreSQL (ADR-002).
Precio -> servidor, desde lista y acuerdos autorizados (RN-03).
Invariantes:
- disponible nunca negativo (INV-01)
- mismo requestId y mismo contenido producen el mismo pedido (RN-06)
BLOCKED que el agente no debe resolver:
- TTL de reserva blanda (RN-07): dueños depósito y comercial.
B.11 Matriz de trazabilidad (RTM)
Cómo completarla: cada fila conecta una evidencia con la regla, la decisión, el cambio y la prueba que la verifica. Si una columna está vacía, la fila no cierra: el código existe pero nadie sabe por qué. Un test que no está en la matriz no defiende ninguna regla. El comando y su resultado son lo que se pega, no lo que se espera que pase.
filas:
- evidencia: EV-05
regla: RN-05
decision: ADR-002
cambio: "src/adapters/postgres-stock.ts"
prueba: "T06 · tests/integration/stock-reservation.test.ts"
comando: "npm run test:integration -- stock-reservation"
resultado: "pendiente de ejecutar en PostgreSQL real"
# EV-03: DECLARACIÓN de la vendedora, reunión 1, minuto 4:
# "Con Platino, si es poco, se pide autorización. Ayer pasó."
- evidencia: EV-03
regla: RN-02
decision: "BLOCKED, sin ADR"
cambio: "ninguno"
prueba: "T04 · pendiente de oráculo"
comando: "no aplica"
resultado: "BLOCKED"
B.12 One-pager de defensa
Cómo completarla: una página que alguien pueda leer en dos minutos antes de una reunión con el cliente. Las decisiones se explican por la consecuencia que evitan, no por la tecnología que usan. "Costo aceptado" y "Qué evidencia la revisaría" son obligatorios: sin ellos, la decisión parece definitiva y no lo es.
# Defensa · <decisión>
Problema que resuelve:
Decisión:
Consecuencia que evita (en términos del negocio):
Costo que aceptamos:
Qué evidencia la revisaría:
Límites de lo que sabemos (BLOCKED o desconocidos):
Preguntas que probablemente nos van a hacer, con respuesta corta:
Ejemplo mínimo de Nexo, para la decisión de monolito modular:
# Defensa · Monolito modular con worker (ADR-001)
Problema que resuelve: consistencia entre pedido, stock y crédito en la misma operación.
Decisión: una aplicación modular con un solo deploy lógico, más un worker para integraciones.
Consecuencia que evita: un pedido confirmado sin reserva, o una reserva sin pedido, por un fallo entre dos servicios.
Costo que aceptamos: escala menos granular; hay que sostener los límites de módulo con disciplina.
Qué evidencia la revisaría: un módulo que necesite escalar o desplegarse de forma materialmente distinta, o un SLA que el despliegue actual no cumple.
Límites de lo que sabemos: TTL de reserva (BLOCKED); tolerancia Platino (BLOCKED).
Pregunta probable: "¿Por qué no microservicios?" Respuesta: no hay un requisito de escala por servicio hoy, y separarlos volvería distribuida una transacción que hoy es local.
B.13 Hoja de entrega
Cómo completarla: es la misma hoja de entrega del manual y del cuaderno de trabajo. Tiene ocho campos y cada uno pide algo distinto. "Tres evidencias" son hechos verificables con su fuente, no la lista de cosas que hiciste. "Decisiones que tomé yo" son las que un agente o una plantilla no podían tomar. Si el campo de desconocidos está vacío después de un trabajo real, probablemente no buscaste lo que no sabés. "Qué tendría que ocurrir para que yo mismo cambie esta conclusión" es una condición observable, no "si el cliente lo pide". En "Revisión de calidad" va solo lo que corregiste o corriste de verdad.
# Hoja de entrega · <nombre del entregable>
Artefacto que entrego y versión:
Tres evidencias que sostienen mis decisiones:
1.
2.
3.
Decisiones que tomé yo y que un agente no podía tomar:
Desconocidos o riesgos que siguen abiertos:
Feedback o propuesta de IA que rechacé, y por qué:
Qué tendría que ocurrir para que yo mismo cambie esta conclusión:
Revisión de calidad: qué corregí antes de enviar o presentar:
Firma del mentor/reviewer o referencia del feedback:
Ejemplo mínimo de Nexo:
# Hoja de entrega · Dossier de discovery, versión 0.3
Artefacto que entrego y versión: 00-brief/dossier-nexo.yaml, v0.3.
Tres evidencias que sostienen mis decisiones:
1. EV-01: el pedido 48172 llegó por WhatsApp y se reescribió en el ERP.
2. EV-02: A-184 se reemplazó por A-184B usando una hoja auxiliar.
3. EV-04: la hoja de acuerdos históricos modifica descuentos.
Fuentes: brief de la dueña (2026-10-12); reunión 1 (2026-10-16), con el pedido 48172 relatado y documentado (foto, hoja de equivalencias, audio).
Decisiones que tomé yo y que un agente no podía tomar: elegí no tratar el portal como solución hasta confirmar el precio final (A.3).
Desconocidos o riesgos que siguen abiertos: U-01 a U-06, con dueño y fecha. Próximo paso: pedir a Laura la exposición de crédito por escrito.
Feedback o propuesta de IA que rechacé, y por qué: el resumen del agente decía "Laura autoriza hasta 10%". Lo rechacé porque nadie dijo un número: la vendedora dijo "Si es poca diferencia, Laura. Si es mucho, Marta."
Qué tendría que ocurrir para que yo mismo cambie esta conclusión: que el responsable comercial muestre que todos los acuerdos de la planilla ya están cargados en el ERP y que el precio final sale de ahí.
Revisión de calidad: qué corregí antes de enviar o presentar: (completar solo con lo que corregiste o corriste de verdad, por ejemplo "parser del repositorio sobre el YAML, sin errores", con la fecha y la salida).
Firma del mentor/reviewer o referencia del feedback: pendiente.
Errores frecuentes
- Síntoma: todos los campos de la RN dicen "a definir". Causa: se copió la plantilla sin tener la evidencia. Corrección: marcar la regla como BLOCKED con la pregunta exacta y el dueño, en lugar de llenar campos con texto de relleno.
- Síntoma: "Autoridad: el equipo" o "Autoridad: se habló en la reunión". Causa: no se preguntó quién decide. Corrección: nombrar a la persona o el documento, o dejar el campo como desconocido.
- Síntoma: la RTM tiene filas con "T-xx" que no existen en el repositorio. Causa: se escribió la matriz antes que las pruebas, o se copiaron IDs de otro proyecto. Corrección: cada fila apunta a un archivo y a un comando que existen.
- Síntoma: el bundle del agente tiene quince páginas y el agente igual inventa una regla. Causa: se copió el manual en lugar de referenciar las RN. Corrección: referenciar por ID, listar los BLOCKED y acotar el contexto al slice.
Repasá el vocabulario de las plantillas antes de usarlas. Dalas vuelta y marcá cuáles dominás.
Vocabulario de plantillas
Frente
Autoridad
Escribí la regla del precio. Esta práctica no tiene respuesta única: se evalúa contra la rúbrica.
Reescribí RN-03 como regla verificable
El equipo dijo que el precio tiene que venir 'del lado correcto'. Escribí RN-03 con el formato de B.2: condición, resultado, autoridad, ejemplo normal, ejemplo frontera, excepción y estado.
Ahora buscá los defectos de esta regla de cliente de contado. Es un borrador real de un alumno.
¿Dónde falla la regla de contado?
Hacé clic en las líneas con problemas. Hay tres.
Para llevarte
- Elegí la plantilla por la pregunta que responde.
- Un campo vacío se completa con DESCONOCIDO o BLOCKED. Nunca con un valor plausible.
- La autoridad es una persona o un documento con nombre.
- El ejemplo frontera es la prueba de que la regla está entendida.
- La trazabilidad no cierra si una columna está vacía.
- Una plantilla que nadie usa para decidir es un formulario. Cortala o rehacela.
Las plantillas completas en formato Markdown están en el cuaderno de trabajo, listas para editar en tu herramienta.
Descargá el cuaderno en Markdown para editarlo en tu herramienta de trabajo.
¿Cómo valoras el contenido técnico de esta lección?
Tu feedback nos ayuda a mejorar los laboratorios prácticos de Eje Z.