ontoref/assets/presentation/intro_slides.md

theme	title	titleTemplate	layout	keywords	download	exportFilename	monaco	remoteAssets	selectable	record	colorSchema	lineNumbers	themeConfig	fonts	drawings	scripts	class
default	Ontología y Reflection — lo que la IA no puede entender por ti	%s - OntoRef	cover	Ontología,Reflection,IA,Infraestructura,OntoRef,Nushell,Nickel	true	ontoref-openspace	true	true	true	true	dark	false	primary logoHeader #f74c00 /ferris.svg	mono Victor Mono	enabled persist presenterOnly syncAll true false false true	setup/image-overlay.ts	justify-center flex flex-cols

La IA gestiona tu infra...
¿Sabes lo que está pasando?

Ontología y Reflection como base de un proyecto que se entiende a sí mismo.

---

layout: default

El problema no es la herramienta

Lo que la IA hace bien

✓

Genera YAML correcto sintácticamente

✓

Completa Terraform que nunca rompe el plan

✓

Rellena gaps de configuración con defaults razonables

✓

Traduce intención en forma declarativa

Lo que la IA no puede hacer

✗

Saber por qué ese servicio no puede escalar a N réplicas

✗

Conocer la tensión que existe entre latencia y consistencia en tu sistema

✗

Recordar la decisión que tomaste en diciembre y por qué descartaste la alternativa

✗

Entender qué no puede romperse sin coordinación entre equipos

Declarativo ≠ comprensión.
Describes el estado deseado, no el por qué.

---

layout: default

Las 2am — cuando el Terraform no habla

Lo que ves cuando falla

Error: Error creating Instance:
  googleapi: Error 400: Invalid value
  for field 'resource.machineType'

# El plan pasó. El apply falló.
# ¿Qué asumió el agente?
# ¿Qué región eligió? ¿Por qué ese tipo?
# ¿Hay una restricción de org que no sabía?

# Lo que generó la IA (hace 6 semanas)
resource "google_compute_instance" "api" {
  machine_type = "e2-medium"   # "razonable"
  zone         = "us-central1-a" # "por defecto"
}

# Lo que tu política de org requiere
# → solo europe-west1, solo n2-standard-*
# → la IA no lo sabía porque tú tampoco lo escribiste

El patrón que se repite

Sin modelo explícito

La IA inventa contexto plausible. Tú asumes que sabe. Falla en prod.

Con Stack Overflow

Copias código sin entender el supuesto. Al menos tú lo buscaste.

Con la IA

El agente genera con confianza. La confianza es contagiosa. El error también.

La diferencia con Stack Overflow:
Al menos ahí buscabas activamente.
Con la IA, delegas también la búsqueda.

---

layout: default

Tu proyecto vive en tu cabeza

Lo que vive solo en tu cabeza

→

Por qué este servicio no puede tener más de 3 réplicas

→

Qué pasó cuando intentamos escalar en enero y por qué fallamos

→

La tensión entre el equipo de plataforma y el de producto sobre quién controla el networking

→

Qué alternativa se rechazó y por qué

→

Qué invariante no puede violarse sin romper el acuerdo con el equipo de seguridad

Lo que vive solo en tu cabeza no se puede validar.
No puede consultarlo un agente.
No puede consultarlo un compañero nuevo.
No puedes consultarlo tú mismo en 6 meses.

La trampa del README

# Mi Proyecto

Este servicio hace X. Está desplegado en GCP.
Usa Terraform. Tiene 3 entornos: dev, staging, prod.

## Arquitectura
Ver diagrama (desactualizado desde marzo).

## Decisiones
- Elegimos PostgreSQL porque MySQL no nos gustaba.
- Usamos gRPC internamente.

✗

No dice qué no puede cambiar

✗

No captura las alternativas rechazadas ni el por qué

✗

No es consultable ni verificable — es prosa

✗

No refleja el estado actual —
refleja el estado de cuando se escribió

---

layout: center

La tesis

La ontología no es para la IA.

Es para ti.

Formalizar invariantes, tensiones y estado actual
te fuerza a saber qué es verdad ahora mismo.

La IA se beneficia como efecto secundario.
Opera sobre lo que tú ya clarificaste.

El valor real: el proceso de escribir la ontología
es donde te aclaras tú, no la IA.

---

layout: default

Ontología ≠ lista de decisiones

Una lista de decisiones

- Elegimos Kubernetes
- Usamos Helm para despliegues
- PostgreSQL como base de datos primaria
- gRPC entre servicios internos
- OAuth2 para autenticación externa

Captura el qué. No captura el por qué,
las alternativas rechazadas, ni las consecuencias.

Una ontología

INVARIANTES

Lo que no puede cambiar sin decisión explícita y coordinación

TENSIONES ACTIVAS

Trade-offs que aún no se han resuelto — viven en el sistema ahora mismo

ESTADO ACTUAL → DESEADO

Dimensiones de madurez. Dónde estás, dónde quieres estar, qué te bloquea

GATES ACTIVAS

Condiciones que deben cumplirse antes de cruzar una frontera arquitectural

Es un grafo consultable. No prosa.
La IA puede leerlo. Tu CI puede verificarlo. Tú puedes razonarlo.

---

layout: default

Ontoref — tres archivos, tres preguntas

core.ncl

"¿Qué ES este proyecto?"

invariantes:
  - backend-agnostic-core
  - zero-external-runtime

tensiones:
  - formalization vs
         adoption-friction
  - ontology vs reflection

prácticas:
  - nickel-as-schema-layer
  - nushell-as-operator

Inmutable sin ADR nuevo.

state.ncl

"¿Dónde ESTAMOS?"

dimensiones:
  backend-maturity:
    actual: multi-stable
    deseado: all-production
    bloqueador: 
         missing-nats-tests

  nickel-depth:
    actual: schema-input
    deseado: bidirectional
    catalizador: 
           export pipeline

Evoluciona con el proyecto.

gate.ncl

"¿Cuándo estamos LISTOS?"

gates:
  core-dependency-gate:
    activa: true
    permeabilidad: Low
    protege:
      - backend-agnostic-core

  nickel-primacy-gate:
    activa: true
    permeabilidad: Low
    protege:
      - nickel-as-schema-layer

Condiciones de cruce.

Nickel tipado · exportable como JSON · consultable desde Nu · verificable en CI

---

layout: default

Reflection — lo que se CONVIERTE

Ontología = lo que ES

→ Invariantes — verdad estructural

→ Tensiones — trade-offs vivos

→ Estado — dónde estamos ahora

Reflection = lo que DEVIENE

→ Modos operacionales — secuencias con DAG de dependencias

→ ADRs con constraints tipadas — decisiones vivas, no prosa

→ Backlog estructurado — tensiones → tareas

→ Historial de sesiones — quién hizo qué y cuándo

La ontología captura el ser.
La reflection captura el operar sobre ese ser.

Un modo como especificación ejecutable ```bash # reflection/modes/new_service.ncl { id = "new_service", trigger = "When adding a new service boundary", steps = [ { id = "draft-adr", actor = "developer", action = "Draft ADR for service boundary decision", }, { id = "verify-invariants", actor = "agent", action = "Check no invariant is violated", depends_on = [{ step = "draft-adr" }], }, { id = "seal-config", actor = "developer", action = "Apply initial config seal", depends_on = [{ step = "verify-invariants" }], }, ], } ```

No es un runbook. Es un grafo acíclico tipado.
La IA lo ejecuta. El sistema lo valida.

---

layout: default

La IA como actor, no como oráculo

Sin ontología formalizada

# Lo que el agente recibe
"Ayúdame a escalar este servicio"

# Lo que el agente asume
- que puede añadir réplicas libremente
- que el estado actual es el deseado
- que no hay restricciones de org
- que la decisión de diciembre es irrelevante

# Lo que genera
resource "google_compute_instance" {
  count = 5  # razonable, ¿no?
}

Con ontología formalizada

# Lo que el agente recibe (SessionStart hook)
INVARIANT: max-replicas-per-zone = 2
TENSION: scaling vs consistency [unresolved]
CONSTRAINT (adr-003): no horizontal scaling
  without explicit capacity review
STATE: backend-maturity = single-stable
  → desired: multi-stable
  → blocker: capacity-review-pending

# Lo que el agente puede hacer
- Preguntar si procede dado el bloqueador
- Generar la config dentro de los límites
- Indicar que el ADR debe revisarse antes

El agente opera sobre lo que tú ya clarificaste.
Deja de inventarse contexto porque tú dejaste de tenerlo implícito.

---

layout: default

¿Quién mantiene esto actualizado?

La pregunta que siempre sale.

El problema real con el README

✗

Nadie tiene incentivo para actualizarlo —
no está en el path crítico

✗

No hay señal de cuando está desactualizado

✗

Actualizar requiere fricción de escritura libre

✗

No hay verificación — puede divergir silenciosamente

El diseño de ontoref

Pre-commit como sincronización forzada

nickel typecheck en cada commit — la capa declarativa nunca queda rota

Modos como procedimientos obligatorios

Añadir un servicio ejecuta el modo — el ADR se escribe como parte del proceso

Drift detection

sha256(nickel export) — sabes cuándo el estado sellado difiere del actual

ADRs como constraints, no prosa

El constraint es machine-readable — el CI puede verificarlo, no solo leerlo

La ontología se mantiene porque es el path.
No porque alguien sea disciplinado.

---

layout: default

Para el debate

Propuesta 1 — Ontología

¿No es suficiente con un buen README?

¿Cuándo fue la última vez que el tuyo estaba al día?

¿Qué diferencia una ontología de una lista de decisiones?

Estructura, consultabilidad, verificabilidad.

¿Quién mantiene esto cuando el proyecto cambia rápido?

El diseño lo hace obligatorio, no opcional.

Propuesta 2 — Infra + IA

¿Es diferente a copiar Stack Overflow?

En SO buscabas. Con la IA, delegas también la búsqueda.

¿Dónde está el mínimo de comprensión necesario?

Saber qué no puede romperse. Sin eso, no tienes control.

¿Las plataformas internas resuelven esto o lo esconden?

Una plataforma sin ontología solo mueve la ignorancia un nivel arriba.

---

layout: cover name: end class: 'justify-center flex flex-cols'

La IA puede declarar tu infra.

No puede entenderla por ti.

La ontología es el modelo que te fuerza a saber qué es verdad ahora.
La reflection es la operación sobre ese modelo.
La IA es el actor que opera sobre lo que ya clarificaste.

Gracias. ¿Preguntas?

jesusperez.pro · ontoref.dev