# Guion mini-demo — Owner por servicio (Opción A) Tiempo total: 8-10 minutos. Lo que hay que teclear y lo que hay que decir, paso a paso. Para la opción B, el ritmo es similar pero con más densidad técnica — ver `option-b-layers/README.md`. ## Pre-requisitos en la máquina del presentador - Terminal con tipografía visible desde la última fila del coworking - Editor con resaltado de sintaxis para Nickel (idealmente) o cualquier editor - Pre-cargado en una pestaña: el `core.ncl` final (`with-contract.ncl`) por si hay bloqueo - `/tmp/demo-wg/` vacío antes de empezar ## Pre-paso (cero, no contar como demo) Limpiar y posicionarse: ```bash rm -rf /tmp/demo-wg && mkdir /tmp/demo-wg && cd /tmp/demo-wg clear ``` --- ## Paso 1 — directorio vacío (~30s) **Teclear:** ```bash pwd ls ``` **Decir:** > Esto es lo que cualquiera de vosotros tiene antes de empezar. Sin framework, > sin scaffold, sin instalar nada. Vamos a montar el esqueleto del approach > con Nickel solo. --- ## Paso 2 — escribir `core.ncl` mínimo (~2 min) **Abrir editor:** ```bash $EDITOR core.ncl ``` **Escribir** (despacio, comentando mientras se escribe): ```nickel { axiom = "Cada servicio en producción tiene un owner identificable", services = [ { name = "api", owner = "backend" }, { name = "frontend", owner = "frontend" }, ], } ``` **Decir mientras tecleas:** > Voy a escribir lo que quiero que sea cierto en mi proyecto: que cada > servicio tenga un dueño identificable. Lo que pongo aquí es texto, todavía > no es contrato. Solo dice que la palabra `axiom` y la palabra `services` > existen. **Validar:** ```bash nickel export core.ncl ``` **Esperar a ver:** el JSON evaluado, sin errores. **Decir:** > Vale, esto pasa. Pero ojo: aquí no he validado nada todavía. Es como tener > un YAML con sintaxis correcta. La estructura es lo único que se garantiza. > Si mañana añado un servicio sin owner, esto sigue exportando sin quejarse. > Vamos a arreglar eso. --- ## Paso 3 — añadir contrato (~3 min) **Editar para que quede así:** ```nickel let Service = { name | String, owner | String, } in { axiom = "Cada servicio en producción tiene un owner identificable", services | Array Service = [ { name = "api", owner = "backend" }, { name = "frontend", owner = "frontend" }, ], } ``` **Decir mientras tecleas:** > Esto es el contrato. Defino qué es un Servicio: tiene un nombre y un owner, > ambos strings. Y le aplico el contrato a la lista — todos los elementos > tienen que cumplir la forma. Esto, en un proyecto real, es lo que en > markdown llamaríais una ADR. La diferencia es que aquí la ADR es código. **Validar:** ```bash nickel export core.ncl ``` **Esperar a ver:** el JSON evaluado, sin errores. **Decir:** > Sigue pasando. Los servicios cumplen el contrato. --- ## Paso 4 — el rompimiento (~2 min) **Decir antes de tocar el código:** > Vale. Ahora viernes por la tarde, hay prisa, hay que meter un servicio nuevo > de métricas. Owner todavía no asignado, ya lo arreglo el lunes. **Editar para añadir el servicio sin owner:** ```nickel services | Array Service = [ { name = "api", owner = "backend" }, { name = "frontend", owner = "frontend" }, { name = "metrics" }, ], ``` **Validar:** ```bash nickel export core.ncl ``` **Esperar a ver:** error que menciona `missing definition for 'owner'` y señala la línea del contrato y el record que viola. **LEER EL ERROR EN VOZ ALTA, despacio.** **Decir:** > El contrato no me dejó. No es un linter post-hoc, no es un test que tarda > cinco minutos en CI. Es la validación del archivo, ahora mismo, en mi > editor. Si esto fuera un PR, el CI falla antes de pasar a review. Tres > meses después, cuando metrics se rompa, no va a ser que nadie sepa quién > lo mantiene. **Pausa larga.** Dejar que la sala procese. --- ## Paso 5 — arreglar y cierre (~1.5 min) **Editar para añadir owner:** ```nickel { name = "metrics", owner = "platform" }, ``` **Validar:** ```bash nickel export core.ncl ``` **Esperar a ver:** el JSON con el servicio nuevo incluido. **Decir:** > Y arreglarlo es trivial. Pongo el owner, pasa. La fricción está en la > decisión, no en escribir el código. **Mostrar tamaño:** ```bash wc -l core.ncl ``` **Esperar a ver:** ~12 líneas. **Decir:** > Doce líneas. Esto es Nickel solo. Sin daemon, sin CLI mía, sin proyecto > enorme. Lo de antes lo construyes en cinco minutos en cualquier proyecto > vuestro. --- ## Volver a slides Cierra el editor (no la terminal — quédate en `/tmp/demo-wg`). Cambia a slidev. La siguiente slide hace el contraste con un `.ontology/` ya crecido. ## Plan B si algo se cuelga | Síntoma | Acción | |---|---| | Editor crashea al escribir | `cp` el archivo del paso correspondiente: `cp /Users/Akasha/Development/ontoref/assets/work-group-ore/demo/option-a-owner/core.with-contract.ncl ./core.ncl` | | `nickel` no responde | Plan B audiovisual: `asciinema play /Users/Akasha/Development/ontoref/assets/work-group-ore/demo/recording/demo.cast` | | Te quedas en blanco mid-demo | Pausa, di "voy a copiar la versión completa para no perder tiempo", `cp core.with-contract.ncl ./core.ncl`, sigue desde paso 4 | | Pregunta inesperada que para la demo | Apunta la pregunta en pizarra, di "lo retomamos después de la demo", sigue | > **Nota técnica**: usamos `nickel export` (no `nickel typecheck`) porque los > contratos `| Array Service` y `std.contract.custom` se evalúan en runtime, > no durante el chequeo de tipos estáticos. `nickel export` evalúa la > expresión a JSON y dispara los contratos en el camino — si alguno falla, el > error sale por `stderr`. Es el comando que mejor refleja "qué pasa cuando > tu CI valida el archivo". ## Errores comunes durante la demo - **No esperar a que la sala lea el error**: la pausa larga después del fallo del typecheck es donde aterriza el insight. Cuenta hasta cinco mentalmente. - **Hablar más rápido cuando uno está nervioso**: el tempo de la demo es lento a propósito. Si te oyes acelerando, respira. - **Disculparse por la simpleza**: NO lo hagas. La simpleza ES el argumento. Si dices "esto es muy simple, en producción es más complicado", pierdes la fuerza del ejemplo.