6.3 Taller E06: producir un bundle revisable

Al terminar esta lección

• Producir un Specification Bundle de CU-01 de máximo seis páginas equivalentes, con contrato de entrada y salida, invariantes y escenarios de aceptación.
• Redactar la sección “el agente no puede decidir” con prohibiciones concretas y verificables.
• Construir una trazabilidad RN/CU → AC → test esperado citando IDs, sin copiar el texto de las reglas.
• Clasificar las preguntas de un agente en huecos de especificación o detalles de ubicación, y corregir el bundle en lugar del prompt.
• Versionar el bundle con baseline y lista de BLOCKED con dueño, y justificar cada criterio del gate con evidencia.

Práctica E06 · Armar el primer Specification Bundle

Situación. Construí el bundle de CU-01 para entregárselo a un desarrollador que no participó de discovery.

Entregá. Bundle de máximo 6 páginas equivalentes; contrato de entrada/salida; invariantes; escenarios.

Está listo cuando. No duplica reglas con redacciones diferentes; todo ID referido está definido; el agente no necesita adivinar autoridad; el fuera de alcance es visible.

Solución comentada: Solución comentada E06. Comparala después de producir tu entrega, no antes.

Armá un Specification Bundle de máximo seis páginas equivalentes para CU-01. El límite de páginas te obliga a seleccionar: si una página no cambia ninguna decisión del slice, sobra; si una decisión cambia el comportamiento y no está escrita, falta.

Qué necesitás a mano

• El modelo conceptual, la matriz de autoridad y el contrato CreateOrder de las lecciones 6.1 y 6.2.
• La caja de reglas de referencia de 6.1. Vas a citar los IDs, no a reescribir el texto.
• El catálogo AC-01 a AC-12 y la frontera IN/OUT/BLOCKED del primer release.
• La lista de archivos autorizados: create-order.ts, stock.ts, postgres-stock.ts y el test de integración de stock. No pegues el repositorio entero.

No copies el manual, las transcripciones de reuniones ni los logs de producción. El bundle se arma con lo que restringe el cambio.

Cómo trabajar los pasos

Cada paso trae un objetivo, un tiempo sugerido, un ejemplo parcial trabajado y el artefacto que producís. Las soluciones parciales están plegadas. La solución completa vive en 14.4: la comparás al final, cuando ya tengas tu versión. Los tiempos suman unos 135 minutos.

Paso 1 · Objetivo observable y fuera de alcance (15 min)

Objetivo. Escribir un objetivo que alguien pueda verificar y un fuera de alcance que alguien pueda defender.

El bundle sigue la plantilla de nueve puntos de la lección 6.1. Para el objetivo hay una prueba simple: tiene que terminar en un resultado observable (pedido confirmado, pedido pendiente de autorización o rechazo con razón), no en un adjetivo. “Que los vendedores carguen pedidos más rápido” no pasa esa prueba, y el bundle v1 de la lección 6.2 lo mostró.

Ejemplo parcial trabajado:

1# Specification Bundle · BUNDLE-CU-01 · v1 (borrador)
2​
3## 1. Objetivo observable
4Registrar un pedido mayorista válido con precio autorizado, crédito evaluado y stock reservado sin sobreventa, o devolver un resultado explícito de por qué no puede aceptarse.
5​
6## 8. Fuera de alcance
7- Recomendaciones de productos, chatbot de WhatsApp y carga de pedidos por foto (OUT).
8- Emisión fiscal con CAE: el pedido queda marcado como pendiente de facturación; la integración real es un corte posterior.
9- Devoluciones complejas y sustituciones automáticas (BLOCKED).

Antes de escribir, decidí qué entra al bundle. La pregunta de corte es siempre la misma: si esta pieza cambia, ¿cambia alguna decisión del slice?

Paso 2 · Reglas focales por ID, sin copiar el texto (15 min)

Objetivo. Listar las reglas y los NFR focales de CU-01 por ID, con cada definición escrita una sola vez en su archivo.

Ejemplo parcial trabajado:

1## 2. Reglas focales (definición única en dossier/reglas/)
2- RN-01 crédito estándar (dossier/reglas/RN-01.yaml)
3- RN-03 precio calculado en servidor (dossier/reglas/RN-03.yaml)
4- RN-05 disponibilidad por depósito y SKU (dossier/reglas/RN-05.yaml)
5- RN-06 idempotencia por requestId (dossier/reglas/RN-06.yaml)
6- RN-08 unidad de venta y RN-09 cliente de contado
7- RN-02 y RN-07: BLOCKED (ver la sección de BLOCKED)
8NFR focales: NFR-01 (registro de pedido con 30 usuarios concurrentes; el umbral se confirma con prototipo), NFR-02, NFR-03 y NFR-04.

Cada línea tiene un ID y una ubicación. No hay frontera ni texto de la regla. Si los agregás, el bundle empieza a tener dos redacciones, y el día que la regla cambie vas a actualizar una y dejar la otra vieja. Esa es la diferencia que muestra la comparación:

Artefacto. La sección 2 del bundle, con una línea por ID y la ubicación de su definición. Si una regla que necesitás no tiene ID, anotala como pregunta para la sección de BLOCKED o para el dueño de la regla.

Paso 3 · Contrato y autoridad de datos (20 min)

Objetivo. Que cada campo del contrato tenga autoridad declarada y que cada resultado de negocio tenga nombre.

El contrato de la lección 6.1 es la base: CreateOrderCommand y CreateOrderResult. No los renombres. Si necesitás cambiar un nombre público, lo escribís en el bundle como decisión, con su motivo, y el agente no puede hacerlo por su cuenta. La autoridad se escribe en un archivo que el agente lee antes de tocar el contrato:

1campos:
2  requestId:
3    autoridad: cliente
4    nota: "clave de la intención; reutilizarla con otro contenido es conflicto (RN-06)"
5  sellerId:
6    autoridad: sesion
7    nota: "si llega en el body se ignora; el servidor usa la sesión"
8  clientId:
9    autoridad: vendedor con cartera
10    nota: "fuera de cartera: forbidden, sin filtrar datos (NFR-03)"
11  items[].sku:
12    autoridad: cliente
13    nota: "debe existir o tener equivalencia vigente (RN-04)"
14  items[].quantity:
15    autoridad: cliente
16    nota: "entero positivo y múltiplo de venta (RN-08)"
17  items[].unitPrice:
18    autoridad: servidor
19    nota: "no existe en el contrato de entrada (RN-03)"
20  deliveryMethod:
21    autoridad: cliente
22    nota: "conjunto cerrado: pickup o delivery; no afecta el precio"

Fijate en items[].unitPrice: la línea no está en el contrato de entrada, así que el agente no tiene dónde meterla. Eso vale más que cualquier validación posterior que la rechace.

Paso 4 · Invariantes y escenarios de aceptación (25 min)

Objetivo. Que cada invariante tenga un defensor concreto y que cada AC tenga datos, acción y oráculo con efectos y no-efectos.

Las invariantes INV-01 a INV-05 se definieron en la lección 6.1. El bundle no las redefine: las lista por ID y dice qué las defiende. Esa columna de defensa es la que vuelve la invariante ejecutable:

1INV-01:
2  enunciado: "la disponibilidad por depósito y SKU nunca queda negativa"
3  defensa: "CHECK en stock_level y prueba concurrente de AC-06"
4INV-02:
5  enunciado: "una intención (mismo requestId) no produce dos pedidos"
6  defensa: "UNIQUE en idempotency_keys y AC-07"
7INV-03:
8  enunciado: "la línea confirmada conserva el precio aplicado y su regla"
9  defensa: "snapshot persistido en la línea y AC-04"
10INV-04:
11  enunciado: "una autorización solo modifica un pedido en estado compatible y queda auditada"
12  defensa: "validación de estado en el caso de uso y AC-08"
13INV-05:
14  enunciado: "un fallo antes del commit no deja efectos; un fallo externo no duplica efectos"
15  defensa: "transacción única con rollback (AC-10) y contrato de fallo fiscal (AC-12)"

Los escenarios son el segundo filtro. Un AC bueno tiene datos concretos, una acción de negocio y un oráculo que dice qué debe existir y qué no. Este es el de SKU inválido, con su no-efecto explícito:

1Escenario: AC-05 un SKU inexistente no deja efectos parciales
2  Dado un cliente con cartera asignada al vendedor
3  Cuando el vendedor envía dos líneas, una de ellas con el SKU "ZZ-000" inexistente
4  Entonces el resultado es rejected con razón invalid_sku
5  Y no existe pedido
6  Y no hay stock reservado para la otra línea

1Escenario: AC-11 el pedido confirmado deja un mensaje de preparación en la misma transacción
2  Dado un pedido que pasó validación, precio y crédito, con reserva firme
3  Cuando el sistema confirma el pedido
4  Entonces existe un mensaje pendiente en la outbox para ese pedido
5  Y el pedido queda marcado como pendiente de facturación
6  Y el proveedor fiscal no se llamó dentro de la transacción
7  Cuando el worker de preparación procesa el mensaje dos veces
8  Entonces la preparación recibe el pedido una sola vez

Paso 5 · Probar el bundle con un agente en modo análisis (25 min)

Objetivo. Medir el bundle por lo que el agente pregunta y decide, no por lo que el equipo cree que dice.

Pedile al agente un plan sin código, con el bundle borrador y el mapa del repositorio, y nada más. El ciclo es corto y se repite hasta que el plan produce solo preguntas de ubicación:

El protocolo tiene cinco pasos. El orden importa:

Cuando el agente pregunta por un valor que el negocio no definió, la respuesta no es elegir uno. Probá con esta situación:

Paso 6 · Revisión adversarial (15 min)

Objetivo. Que una persona o un agente intente inventar negocio con el bundle, y que registres dónde lo logra.

La sección de prohibiciones es la que más se degrada en un bundle. Revisá este fragmento y marcá las líneas que no son prohibiciones verificables:

Después de la auditoría de la sección, seguí el Cuaderno de campo 06 más abajo, que te propone la revisión completa con otra persona o con un agente. Si la revisión encuentra algo que el bundle no decide, no lo arregles en la conversación: va al bundle.

Paso 7 · Trazabilidad, BLOCKED y baseline (20 min)

Objetivo. Cerrar la cadena RN/CU → AC → test, señalar los tests sin criterio y versionar el bundle con su lista de bloqueos.

La trazabilidad liviana necesita solo IDs. El diagrama muestra la cadena para los casos más sensibles, y la tabla la extiende a todo el catálogo:

La tabla tiene dos filas sin AC. No es un error de la tabla: es una pregunta. Un test sin AC puede venir de un NFR o de una máquina de estados, y en ese caso se traza a su origen. Si el hueco es un comportamiento de negocio sin criterio, el arreglo es agregarlo al catálogo, sin cambiar los IDs existentes.

Ahora el baseline. Un bundle sin lista de BLOCKED con dueño no está versionado; está en un borrador que cualquiera puede cambiar. El skeleton del archivo es este:

1bundle: BUNDLE-CU-01
2version: v1
3fecha: AAAA-MM-DD
4alcance_aprobado: "plan y diseño; no implementación de reglas BLOCKED"
5aprobado_por: "nombre y rol de quien aprueba"
6cambios_desde_anterior:
7  - "describí cada cambio y la evidencia que lo motivó"
8bloqueados:
9  - { id: RN-02, falta: "tolerancia Platino", responsable: "Marta y Laura" }
10  - { id: RN-07, falta: "plazo de la reserva blanda", responsable: "depósito y comercial" }
11  - { id: cheques, falta: "tratamiento de cheques pendientes", responsable: "administración" }
12  - { id: sustituciones, falta: "matriz de compatibilidad", responsable: "a asignar en la revisión" }
13  - { id: multi-deposito, falta: "criterio para elegir depósito en pedidos grandes", responsable: "a asignar en la revisión" }

Los dueños de RN-02, RN-07 y cheques vienen del caso. Los de sustituciones y división multi-depósito no están definidos en el caso: la revisión tiene que asignarlos. Si no podés asignar un dueño, el BLOCKED no está listo para el baseline; es un desconocido que sigue abierto.

Nexo B2B · El bundle que parecía completo hasta que el agente hizo una pregunta correcta

El equipo prepara el primer Specification Bundle de CU-01 y se lo entrega a un agente para que proponga un plan, no para que programe. Incluye caso de uso, RN-01 a RN-05, contrato HTTP, modelo conceptual y ADR de persistencia. La respuesta del agente empieza bien: identifica endpoint, use case, repositorio y tests. Después pregunta: “Si la lista de precios cambia entre la creación del borrador y la confirmación, ¿debo recalcular el total o conservar el snapshot anterior?”. El documento no lo decía.

La tentación es contestar desde ingeniería. Conservar el snapshot parece conveniente, recalcular parece consistente con la lista vigente. Ninguna opción es evidencia. El equipo vuelve a Nexo con dos episodios concretos. Ventas explica que una cotización enviada al cliente puede respetarse hasta el cierre de ese día, mientras que un pedido todavía no cotizado toma la lista vigente al confirmar. Esa distinción obliga a separar “borrador interno” de “oferta comprometida”. El bundle se corrige antes de que exista una línea de código.

Aparece una segunda grieta. El contrato recibía unitPrice porque la pantalla ya calculaba el total. El agente propone persistirlo. El reviewer lo rechaza: el frontend no es autoridad de precio. El request puede transportar un valor mostrado para detectar desactualización o mejorar UX, pero el servidor vuelve a resolver el precio y responde el aplicado. Si hay una diferencia que deba ser confirmada por el usuario, ese comportamiento necesita una regla explícita. Nunca se convierte silenciosamente el input manipulable en verdad del dominio.

El bundle final queda deliberadamente pequeño. Contiene el objetivo observable, precondiciones, RN necesarias, contratos, invariantes, decisiones arquitectónicas focales, escenarios de prueba y referencias a archivos del repositorio. No contiene el manual entero ni cuarenta páginas de contexto general. También tiene una sección “No decidir” con tres puntos: TTL de reserva todavía BLOCKED, política de división multi-depósito fuera del slice y reglas de descuento extraordinario sin evidencia suficiente.

Esta revisión enseña algo que el equipo mantiene durante todo el proyecto: una buena interacción con IA puede revelar una deuda de especificación, pero la respuesta no se obtiene preguntándole cuál opción prefiere. El agente detecta el hueco. La autoridad para cerrarlo sigue estando en evidencia, reglas aprobadas y decisiones humanas registradas.

Nexo B2B · Expediente 06: autoridad campo por campo

CreateOrder acepta clientId, líneas y deliveryMethod. El precio mostrado en UI es informativo y puede enviarse como referencia, pero nunca manda. El servidor resuelve precio vigente. El estado no es libre. La categoría de crédito viene de la fuente autorizada. requestId identifica intención. Esta matriz de autoridad evita que un DTO se convierta accidentalmente en modelo de confianza.

La misma idea aplica a eventos externos. Un webhook fiscal puede ser fuente de un estado de comprobante, pero debe autenticarse y correlacionarse. Un mensaje de WhatsApp no puede por sí mismo cambiar crédito. Cada boundary necesita entender qué afirma la entrada y qué debe volver a verificar.

Cuaderno de campo 06 · Bundle adversarial

Entregable. Specification Bundle y una revisión adversarial hecha por otra persona o por un agente.

1. Pedí al revisor que intente implementar una regla sin consultar negocio. Registrá qué partes del bundle le permiten o le impiden inventar.
2. Pedí que liste datos que podrían ser manipulados por el cliente. Revisá la autoridad de cada uno contra la matriz.
3. Pedí que encuentre duplicación textual de RN. Reemplazá las copias por referencia cuando sea seguro.
4. Sacá del bundle un documento que parezca útil y verificá si el plan cambia. Si no cambia, era ruido.
5. Versioná el bundle con fecha, baseline y lista de BLOCKED. La conversación del agente no cuenta como versión.

Criterio de revisión. Contexto compacto no significa incompleto. El bundle debe omitir ruido y conservar todo lo que puede cambiar el comportamiento del slice.

Hoja de entrega 6 · completá antes de pasar el gate

Este bloque no se completa “de memoria”. Volvé a tus artefactos, evidencia y resultados. El objetivo es hacer explícito qué vas a defender frente a un mentor o cliente.

• Artefacto que entrego y versión:
• Tres evidencias que sostienen mis decisiones:
• 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:

Gate 6 · el slice tiene baseline

Guardá tu entrega

Cuando termines tu entrega, compará tu razonamiento con la solución comentada E06. No hay una única respuesta correcta: la comparación busca fuentes, decisiones y evidencia.

1Rol: analista técnico. Planificás, no escribís código.
2Entrada: el bundle BUNDLE-CU-01 borrador adjunto y el mapa del repositorio.
3Tarea:
41. Listá cada decisión que tendrías que inventar para implementar el slice. No propongas valores.
52. Clasificá cada pregunta como UBICACIÓN (dónde está algo), NEGOCIO (qué debe pasar) o EVIDENCIA FALTANTE (un BLOCKED).
63. Para cada AC-01 a AC-12, indicá el archivo o test que lo verifica, o escribí "no existe".
7Regla: si una regla figura como BLOCKED, no propongas un valor; pedí que se parametrice. Si falta evidencia, escribí "falta evidencia" y no completes.

Errores frecuentes

• Síntoma: el agente vuelve a inventar la misma decisión después de cambiar el prompt. Causa: el hueco está en el bundle, no en las instrucciones. Corrección: volver a la sección donde nace la decisión, escribirla con evidencia o marcarla BLOCKED.
• Síntoma: un test de la matriz no tiene ningún AC. Causa: la matriz de pruebas y el catálogo se escribieron por separado. Corrección: trazar el test a su NFR, RN o máquina de estados; si el comportamiento es de negocio y no tiene criterio, agregar un AC al final del catálogo.
• Síntoma: la sección “el agente no puede decidir” termina en “lo que considere razonable”. Causa: la lista se cerró con un comodín. Corrección: reemplazar el comodín por una prohibición concreta o por la instrucción de preguntar.
• Síntoma: la trazabilidad tiene el texto completo de las reglas. Causa: la tabla se armó pegando definiciones. Corrección: dejar solo IDs; la definición vive en su archivo.
• Síntoma: el baseline dice “v1” sin fecha y sin lista de BLOCKED. Causa: el gate se cerró por inercia. Corrección: fecha, cambios desde la versión anterior y BLOCKED con dueño, antes de declarar el slice listo.

Para llevarte

• Un bundle se prueba con un agente en modo análisis: lo que el agente pregunta y decide mide la calidad del bundle.
• Las correcciones van al artefacto donde nace la decisión, no al prompt.
• Cada campo del contrato tiene autoridad declarada; precio, crédito, estado y reserva nunca vienen del cliente.
• La trazabilidad cita IDs y deja visibles los tests sin AC, que siempre señalan un hueco o un test de más.
• Un valor BLOCKED se parametriza y tiene dueño; nunca aparece como constante ni como default.
• El baseline es una versión con fecha, cambios explícitos y lista de bloqueos. La conversación del agente no cuenta como versión.