ontoref/assets/work-group-ore/demo/script.md

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:

rm -rf /tmp/demo-wg && mkdir /tmp/demo-wg && cd /tmp/demo-wg
clear

---

Paso 1 — directorio vacío (~30s)

Teclear:

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:

$EDITOR core.ncl

Escribir (despacio, comentando mientras se escribe):

{
  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:

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í:

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:

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:

  services | Array Service = [
    { name = "api", owner = "backend" },
    { name = "frontend", owner = "frontend" },
    { name = "metrics" },
  ],

Validar:

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:

    { name = "metrics", owner = "platform" },

Validar:

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:

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.