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:

```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.