Escribí la ontología de un producto. Tres veces creí haber terminado.

Llega una pregunta por Slack: ¿el producto sabe hacer esto, para este cliente, en este caso concreto?

No es una pregunta abstracta. No es una reflexión sobre la visión a cinco años. Es una pregunta de campo, y hay que responderla dentro de la hora. Así que alguien abre un entorno de pruebas, reproduce el caso, comprueba. Media hora. Pagada dos veces: por la persona que busca y por la que ha interrumpido.

Esto no es un problema de documentación. La hay, y está al día. El problema es que aquello de lo que está hecho el producto — los objetos que maneja, las reglas que los rigen, las palabras para hablar de ellos — no está escrito en ningún sitio de una forma que se pueda consultar. Existe en dos sitios: en el código, que unas pocas personas saben leer, y en la cabeza de esas mismas personas.

Así que intenté escribirlo. El resultado existe: 52 objetos descritos, 250 reglas, 208 vínculos entre ellos. Este artículo cuenta cómo llegué ahí — y sobre todo lo que hice mal por el camino, porque esa es la parte que se transfiere.

Tres advertencias antes de empezar.

La primera: este informe trata de la fabricación del modelo de referencia, no de su uso. Existe, está medido, ya ha producido sus primeros subproductos. Pero la fase de explotación no ha empezado. Así que no puedo afirmar nada sobre el retorno de la inversión. Quien te venda una cifra a estas alturas se la está inventando.

La segunda: los ejemplos vienen de un caso ficticio — una empresa que vende un SaaS de gestión, un ERP, con sus clientes, sus pedidos, sus líneas y sus facturas. Lo que se transfiere de un producto a otro no son mis hallazgos, es el tipo de problema que aparece: un estado recalculado en todas partes y definido en ninguna, una regla aplicada de un solo lado, una palabra que los clientes usan y que el producto desconoce. Esos tres los tienes tú también. El detalle del caso, en cambio, no le interesa a nadie.

La tercera: es largo, media hora de lectura. Es un informe, no un post — he preferido decirlo todo antes que ser breve. Si solo vas a leer una sección, lee "Tres criterios de parada. Tres veces mal.": el resto es el contexto que la rodea. Los anexos solo sirven a quien quiera repetir el trabajo.

Una ontología no es un glosario enriquecido

La palabra es una trampa. A unos les evoca filosofía, a otros un campo académico con herramientas complicadas, y a la mayoría nada en absoluto. Mejor dejarlo claro.

Una ontología es la descripción explícita y estructurada de aquello de lo que está hecho un dominio: - los tipos de objetos que existen, - lo que los caracteriza, - lo que los conecta, - lo que es verdad sobre ellos, - las palabras con las que los llamamos.

Aplicada a un software, responde a cinco preguntas. Cada una corresponde a algo que se escribe, y cada una tiene un nombre erudito que después no vas a necesitar:

En el resto del artículo, para evitar los términos eruditos, digo "objetos", "propiedades", "vínculos", "reglas" y "palabras". Es lo mismo.

Esas cinco casillas también sirven de filtro: lo que no entra en ninguna no tiene nada que hacer en el modelo de referencia.

Por qué un documento más

Ya existía un glosario, un esquema de base de datos y documentación. El glosario define palabras de una en una. El esquema ordena datos según restricciones técnicas, no según el negocio. La documentación narra, para un lector humano.

Lo que las distingue de una ontología se resume en un punto: los vínculos cuentan tanto como las definiciones. Un objeto descrito solo enseña poca cosa. El mismo objeto conectado a cinco otros por verbos precisos — hecho por, contiene, facturado en — describe un producto.

Lo que reconcilia

Un mismo objeto lleva tres nombres dentro de una empresa. Tomemos el pedido de cliente:

Esos tres vocabularios evolucionan por separado, y la diferencia entre ellos es información valiosa. El modelo de referencia la conserva: la palabra oficial, las palabras que usan los clientes y las que abandonamos por el camino. Es lo que permite traducir la frase de un usuario en objeto del producto — y al revés.

Lo que no hice

Hay maneras muy eruditas de hacer todo esto: lenguajes dedicados, herramientas que deducen conclusiones a partir de las reglas que les das, normas que las acompañan. Es un campo de verdad, y no entré en él (entre otras cosas, por falta de competencias).

Empecé por lo que sabía sostener: una ficha por objeto, en un archivo de texto. Un título, unos cuantos campos, vínculos hacia las demás fichas. Nada que un editor de texto no pueda abrir. Mientras no sepa para qué va a servir el modelo de referencia, no sé cuánto rigor necesito — y empezar simple para complicarse después siempre cuesta menos que lo contrario.

El código se convirtió en la fuente de verdad. El sentido se quedó fuera.

Alrededor de este producto, la documentación, el registro de novedades, la documentación de soporte, las respuestas a las preguntas de producto y las especificaciones se regeneran a partir del código. El razonamiento es simple: la verdad de un producto es lo que se ejecuta, no lo que se había previsto.

Ese cambio elimina un trabajo entero: mantener al día, a mano, documentos que describen algo distinto de la realidad. Es una ganancia considerable, y la seguiría defendiendo.

Pero desplaza el problema.

Lo que el código no da

El código establece cómo funciona el producto. El sentido se construye por encima.

Tomemos el pedido y su estado. El código da la estructura: aquí están los campos, aquí están los valores posibles. Cuatro informaciones lo vuelven realmente explotable, y ninguna está ahí:

• la regla — un pedido facturado no recibe más líneas. El producto lo aplica, pero la regla no está escrita en ningún sitio: la comprobación está repartida en cinco archivos y cada uno hace solo una parte. Para enunciarla en una frase hay que haberlos leído los cinco;
• los casos particulares — un pedido urgente es un pedido, con restricciones de más;
• el vocabulario — los usuarios dicen "negocio", y otro término se abandonó hace tres años;
• el alcance — el producto tiene dos aplicaciones, que llamaré A y B, y cada una pone su propio sentido detrás de la misma palabra.

Reunidas, esas cuatro informaciones convierten una estructura de datos en descripción de producto. Es exactamente el contenido de una ficha. Y ninguna está en el mismo sitio: están repartidas entre el núcleo del código, la base de datos, las pantallas y las traducciones.

El coste real se paga en otro lado

La pregunta del principio es solo un caso entre otros. Todo lo que describe el producto a alguien es una reconstitución, rehecha cada vez, en paralelo, por cada área: la documentación, las respuestas a propuestas comerciales, la formación de quien llega, el discurso del soporte. Cada uno vuelve a partir del código, o de la memoria de alguien.

Es ese gasto el que hay que eliminar. No aparece en ningún presupuesto, lo que explica que lo llevemos pagando años sin verlo.

Una IA no puede preguntar. Adivina.

Hasta ahora, lo que el producto realmente es se transmitía de viva voz. Preguntabas a la persona adecuada, obtenías la regla y volvías al trabajo. El modelo del producto vivía en unas pocas cabezas, y funcionaba porque siempre se podía llamar a una puerta.

Una IA no llama a ninguna puerta.

Cuando le encargas una evolución, la describes en unas cuantas frases. En nuestra cabeza hay un modelo completo: qué es un pedido, qué estados atraviesa, qué está prohibido y desde cuándo. El agente solo tiene nuestras pocas frases, más lo que consigue leer en el código. El resto lo rellena — de forma plausible, coherente y a veces falsa.

La diferencia entre lo que queríamos y lo que recuperamos es exactamente la parte de nuestro modelo mental que no hemos escrito.

Un modelo de referencia es ese modelo mental escrito. Dárselo a un agente no lo vuelve más inteligente: le impide inventar donde ya existe una regla. De ahí salen tres usos, y son los que me interesan.

Pedir una evolución sin volver a explicar el producto. "Añade un descuento en los pedidos." Con el modelo de referencia en el contexto, el agente sabe que un pedido facturado no recibe más líneas, que un descuento tiene un tope y que "pedido" cubre también los pedidos urgentes y los pedidos recurrentes. Sin él, descubrirá una de esas tres cosas en la revisión — en el mejor de los casos.

Analizar más rápido. Instruir un bug empieza siempre por reconstituir el modelo de la zona afectada. Esa reconstitución se rehace cada vez, por cada persona y por cada agente. Escrita una vez, se lee en unos segundos. Y unos cientos de fichas caben en un contexto donde miles de archivos de código no caben: el agente lee lo que hace falta en vez de rebuscar al azar.

Escribir las pruebas y zanjar los avisos. Una regla es una afirmación verificable. "Un pedido facturado no recibe más líneas" es una prueba, tal cual, formulada en lenguaje de negocio. 250 reglas son 250 pruebas candidatas que nadie tiene que deducir del código. Y ante un aviso de cliente, la pregunta se vuelve mecánica: ¿contradice esto una regla escrita? Entonces es un bug. ¿O es una regla que nadie había fijado? Entonces es una decisión de producto, no un defecto. Hoy ese veredicto se emite por experiencia, por la persona con más antigüedad del equipo.

Nada de esto está medido, conforme a la advertencia del principio. El mecanismo me parece sólido — se elimina la parte adivinada — pero no he hecho la prueba. La que haré: coger una treintena de peticiones, tratar la mitad con el modelo de referencia en el contexto y la otra mitad sin él, y comparar el tiempo empleado y la cantidad de retrabajo. Mientras eso no esté hecho, esta sección es una expectativa, no un resultado.

El método: esbozar para saber qué buscar

Un dilema aparece de entrada. Sin un modelo, aunque sea burdo, no sabes qué material recoger — y pasas al lado de informaciones importantes sin saberlo. Sin material, no sabes qué modelo sostener.

Iterar, no secuenciar. Esbozas lo justo para saber qué buscar, buscas, y revisas el modelo con lo que has aprendido. Una restricción atraviesa las idas y venidas: lo que se recoge se guarda en la forma más simple posible, y siempre con la indicación de dónde viene. Un cambio de modelo nunca debe obligarte a volver a buscar lo que ya tienes.

Por dónde empezar: veinte preguntas que ya nos habían hecho

Un producto tiene decenas de áreas: la facturación, las compras, los permisos de acceso, la búsqueda, las notificaciones. ¿Por cuál empezar? La respuesta teórica se conoce: primero se escriben las preguntas a las que el modelo de referencia tendrá que responder, y ellas delimitan el terreno. El problema es que las preguntas escritas en frío, en una sala, siempre se parecen a lo que creemos importante.

Así que no las escribí. Fui a buscarlas.

Desde hace meses, cada pregunta de producto que llega — por Slack, en una reunión, de un comercial que prepara una respuesta, del soporte ante un ticket — se archiva con su respuesta. Las releí todas y luego las condensé en veinte preguntas genéricas. Ninguna está inventada; cada una cubre entre cinco y veinte preguntas reales.

Transpuestas al ERP ficticio, quedan así:

• ¿Cuáles son los estados de un pedido, y qué pasos de uno a otro están permitidos?
• ¿Qué se puede cancelar todavía, y desde qué momento ya no?
• ¿Qué es el saldo de un cliente, y por qué movimientos evoluciona?
• ¿De quién es un pedido generado automáticamente, y qué ocurre con él si esa persona deja la empresa?
• ¿En qué casos un usuario de una filial ve los pedidos de otra filial?
• ¿Cómo llaman los usuarios al pedido, y en qué idiomas?

No son preguntas elegantes. Son las que le cuestan media hora a alguien, varias veces al mes.

Lo que eso da de inmediato: el orden de trabajo. Cada pregunta toca una o varias áreas del producto; solo hay que contar. Once preguntas de veinte daban en la misma área — se convirtió en la primera. Cinco en una segunda, cuatro en una tercera. El orden deja de ser una preferencia y pasa a ser un recuento.

Y sirven una segunda vez, a la llegada. Cuando un área termina, se retoman sus preguntas y se comprueba que el modelo de referencia responde sin abrir el código. La comprobación hecha a mitad de camino dio 18 respuestas completas de 20. Las dos que faltaban fallaban de la misma manera: una regla escrita en general donde la pregunta esperaba el detalle — "ciertas operaciones exigen esto" sin decir nunca cuáles.

Ese es el defecto más probable de este tipo de trabajo, y el más difícil de ver. Contar fichas nunca lo habría mostrado.

Una ficha por objeto, y vínculos entre ellas

Una ficha por objeto de negocio, en un archivo de texto que lleva su nombre. Cada vez que una ficha menciona otro objeto, lo hace mediante un vínculo.

Ese detalle parece cosmético. No lo es. Las fichas y sus vínculos forman una red, y esa red se puede visualizar: cada ficha es un punto, cada vínculo un trazo. Un vínculo que apunta a una ficha que todavía no existe se ve de inmediato — es la señal de que queda un objeto por describir.

La red deja entonces de ser una imagen bonita y se convierte en la cola de trabajo: mientras queden vínculos apuntando al vacío, quedan fichas por escribir.

La realidad de un lado, la intención del otro

Un modelo de referencia puede describir dos cosas muy distintas: lo que el producto hace o lo que debería hacer. Cada una por separado es incompleta. La primera nunca permite hacer aparecer un defecto. La segunda pierde el rastro de lo que existe de verdad.

Yo guardo las dos, en dos sitios distintos de la misma ficha. El cuerpo de la ficha describe la realidad, tal como está en el código. Un bloque separado, al final de la ficha, lista las desviaciones: cada punto donde esa realidad diverge de lo que querríamos.

Regla absoluta: una desviación nunca modifica el cuerpo de la ficha.

Lo que justifica la separación es que las dos partes no tienen la misma duración de vida:

El cuerpo se deduce del código: se puede tirar y rehacer sin perder nada. Las desviaciones llevan juicio — no se encuentran en ningún sitio si se pierden. Separarlas es proteger la parte que cuesta caro producir.

Un punto que suele entenderse mal: cuando todo va bien, no se escribe nada. Si el producto hace lo que debe, la regla simplemente figura en el cuerpo de la ficha. El bloque de desviaciones solo contiene las divergencias. Una ficha sin desviación señala un objeto conforme, y eso ya es información.

Cinco naturalezas de desviación bastan, y son ellas las que convierten el modelo de referencia en material de trabajo:

El punto de partida: una foto, tomada en un instante dado

Se describe el producto tal como está en un instante dado. Una versión del código, y todo lo que se ejecuta con ella: la base tal como está en esa versión, las pantallas de esa versión, las traducciones de esa versión. Esa es la foto.

Lo que figura en ella es el estado inicial, sin fecha de nacimiento: no busco saber cuándo apareció cada campo. Reconstituir la historia del producto exigiría rebuscar en años de archivos para un beneficio nulo.

Más tarde se toma una foto nueva y se actualizan las fichas con lo que se ha movido entre las dos. Ese es todo el mecanismo.

Lo único que hay que vigilar, y ahí me pillaron: una fuente que no viene de la foto no es una fuente. Vuelvo a esto más abajo.

Cuatro sitios que leer, ninguno opcional

Un mismo objeto está descrito en cuatro sitios del producto, y cada uno dice lo que los demás callan:

Un área del producto solo está terminada cuando se han leído los cuatro. Una regla puede existir perfectamente en uno solo.

Las pantallas se leen después del núcleo del código, y antes de cerrar el asunto. No es una exigencia de exhaustividad, es una máquina de encontrar desviaciones:

Una regla presente únicamente en la pantalla casi siempre es una desviación.

O es una regla de negocio de verdad, mal colocada — una fricción. O se puede esquivar pasando al lado de la pantalla, por una importación de archivo o por la interfaz que el producto expone a desarrolladores externos: su API. Y entonces es un defecto, con un asunto de seguridad detrás: lo que la pantalla prohíbe, otro camino lo autoriza.

El caso inverso existe y se trata igual. Una regla aplicada por el núcleo del código pero que la pantalla no refleja produce un mensaje de error incomprensible: al usuario le rechazan la acción sin que vea qué ha hecho mal.

Dos constataciones sobre esta lectura de las pantallas.

Primero, el reparto de las pantallas no coincide con el del código. Doce zonas de la interfaz no tenían zona equivalente en el lado servidor. Así que el emparejamiento se hace objeto por objeto, nunca carpeta por carpeta.

Segundo, un truco que vale oro en las partes menos ordenadas del código: los nombres de los mensajes de error técnicos suelen ser la mejor fuente de reglas. Un desarrollador que rechaza una acción crea un caso de error, y le pone nombre. Un error llamado CannotEditInvoicedOrder — "no se puede editar un pedido facturado" — enuncia una regla por sí solo. Basta con leer la lista de esos nombres, lo que no exige saber programar.

Nada de esto es original

Puede que este sea el punto más útil de la sección. Construir ontologías es una disciplina establecida, con su literatura, y el método de arriba solo retoma resultados conocidos:

• Lo iterativo antes que la cascada. Los métodos históricos encadenaban las etapas en orden: especificar, concebir, formalizar, realizar. Fueron sustituidos por enfoques de piezas pequeñas recombinables. El debate está zanjado desde hace unos quince años.
• El encuadre por preguntas. Escribir primero las preguntas a las que el modelo de referencia tendrá que responder es el dispositivo estándar; incluso tiene nombre, competency question. Ir a buscarlas al soporte en vez de escribirlas en frío no está en los manuales. No cuesta nada, y cambia lo que encuentras.
• Partir del medio. Se empieza por los objetos más centrales del negocio, luego se sube hacia las categorías más amplias y se baja hacia los casos particulares. Las otras dos maneras fracasan: partir de la base de datos equivale a copiar la estructura técnica tal cual, con sus tablas que no significan nada para el negocio; partir de una teoría general de lo que existe da un edificio fuera de proporción con la necesidad.
• Rigor proporcionado al uso. Uno se complica la vida cuando lo necesita, no por principio.
• No reinventar lo que ya está normalizado. En la mayoría de los sectores existen clasificaciones de referencia. Hay que mirarlas — y tratar cualquier divergencia entre tu propio modelo y ellas como una cuestión que instruir, no como un detalle.

Tres criterios de parada. Tres veces mal.

Esta es la parte por la que existe este artículo.

Primero, dos estrategias descartadas

Saber qué buscar no dice en qué orden recorrer el producto. Dos enfoques se presentan de forma natural, y los dos fracasan.

Leerlo todo, en el orden de los archivos. Sin prioridad, no hay orden de llegada ni estructura que emerja. La organización de las carpetas no tiene ninguna relación con la importancia de negocio, y lo que está ahí solo por razones técnicas queda descrito al mismo nivel que los objetos de negocio de verdad. Acabas con una masa de fichas sin saber cuáles cuentan.

Partir de la base de datos y hacer una ficha por tabla. Útil, pero insuficiente, y basado en una confusión: una tabla no es un objeto de negocio. Muchas tablas solo sirven para enlazar dos otras tablas, guardar un rastro técnico, almacenar tokens de conexión o resultados temporales. No tienen ningún sentido para quien habla del producto.

Así que elegí una tercera vía: un área del producto a la vez, partiendo del núcleo del negocio hacia la periferia, apoyándome en el reparto que el código ya lleva. Un software algo grande está dividido en módulos — zonas de código que corresponden a grandes rasgos a áreas del negocio: la facturación, las compras, los permisos de acceso. Ese reparto lo hicieron desarrolladores, pero ya constituye una descripción parcial del negocio, gratuita y validada por el uso.

Fue la decisión correcta. No impidió lo que vino después.

Primer criterio: "la red de fichas está cerrada"

Todas las fichas citadas existen, ningún vínculo apunta ya al vacío. Así que se ha terminado.

Es falso, y la razón es mecánica. Un conjunto de fichas que solo se citan entre sí cierra su red mucho antes de haber cubierto el producto. La red se cerró en mi caso cuando solo doce módulos de treinta y dos habían dado lugar a una ficha.

Lo que esa comprobación probaba de verdad: que el conjunto se sostiene. Nada más. Es una buena comprobación, hay que conservarla — pero no responde a la pregunta planteada.

La comprobación de cobertura hecha después reveló dos objetos centrales del negocio que nada, en la red, estaba reclamando.

Segundo criterio: "he recorrido todas mis fuentes"

El código de las dos aplicaciones, la base de datos, la API, el glosario, las notas de entrevistas, los tickets de soporte. Nada más que abrir.

Es cierto, y no prueba nada. Es una afirmación sobre lo que he abierto, no sobre lo que existe. "He leído todo mi montón" no dice nada de la biblioteca: mientras el producto no esté enumerado, "todo" no tiene denominador. Un módulo que nunca figuró en mi lista tampoco figura en mi "todo".

Tercer criterio: "cada área se ha leído en los cuatro sitios"

El núcleo del código, la base de datos, las pantallas, las traducciones.

Cierto también, e insuficiente por la misma razón: solo vale para las áreas que había identificado. El criterio mide la profundidad, no dice nada de la anchura. Se pueden leer cuatro sitios en doce módulos e ignorar veinte — es exactamente lo que ocurrió.

El diagnóstico

Retomemos los tres, y lo que cada uno probaba de verdad.

Los tres dicen lo mismo: he terminado lo que había empezado. Ninguno dice: no queda nada.

Elegimos un criterio que podemos satisfacer, en vez de un criterio que prueba el trabajo hecho.

Es la diferencia entre "he ordenado todo lo que había en mi mesa" y "aquí está la lista de lo que tenía que ordenar, todo marcado". La primera frase es verdadera, y no compromete a nada. La segunda supone haber hecho la lista antes de empezar.

Esto no es deshonestidad, es una cuestión de coste.

Un criterio que puedes satisfacer ya lo tienes a mano: basta mirar lo que acabas de hacer y constatar que está hecho. Un criterio que prueba, en cambio, exige fabricar algo más: la lista de lo que existe, una forma de contarla, una cifra que otro pueda recalcular. Es trabajo adicional, reclamado en el momento exacto en que crees haber terminado.

De ahí la única defensa que conozco: elegir el criterio de parada al principio, no al final. Buscarlo al final es elegirlo entre los que ya estás seguro de satisfacer.

El único criterio que aguanta

Enumerar el producto desde varios ángulos independientes y medir, para cada uno, la parte que corresponde a una ficha.

Cada ángulo ve lo que los demás no pueden ver:

Y sobre todo: la señal útil es el desacuerdo entre dos ángulos. Un objeto presente en uno y ausente de los demás es o un objeto de negocio que se nos ha escapado, o parte puramente técnica. La cuestión se zanja en una línea — pero se zanja explícitamente, nunca de pasada.

Los otros errores

Cuatro, más pequeños, todos costosos.

Leer una fuente que no estaba en la foto. La exportación de la base de datos que tenía se había generado cinco meses antes de la versión de código que describía. La leí como si describiera el mismo producto. Describía un producto más antiguo: en un área entera, los objetos estaban ahí en el código sin ninguna tabla correspondiente en la exportación, y concluí que no existían.

La regla es más simple de lo que creía en ese momento. No es "verificar la fecha antes de concluir", es que una fuente que no viene de la foto no es una fuente. Se sustituye por una versión al día, o se prescinde de ella.

Y la precisión que cuenta, porque al principio se me pasó: cuando dos partes de la misma foto se contradicen — el código de un lado, la base o la pantalla del otro, en el mismo instante, en producción —, eso no es un desfase. Es una incoherencia del producto. Es exactamente lo que buscamos.

Confundir una búsqueda con un inventario. Había indexado todo el código en un motor de búsqueda por sentido — el principio del RAG: haces la pregunta en lenguaje corriente y la herramienta trae los pasajes más cercanos. Es tremendamente eficaz para reencontrar una regla enterrada en medio de un archivo, que nada en su nombre señalaba.

Pero un motor de este tipo siempre responde, y siempre responde con una clasificación: aquí están los diez pasajes más cercanos a tu pregunta. Nunca dice "no hay ninguno". Una búsqueda que no trae nada interesante puede significar entonces dos cosas: que la cosa no existe, o que he formulado mal la pregunta. Imposible zanjarlo.

De ahí la regla: enumerar primero, buscar después. En el sentido contrario, obtienes un modelo de referencia hecho de lo que el motor ha tenido a bien traer.

Dos detalles que cuestan caro. El motor tenía su propia fecha, una versión por detrás del código. Y hay que hacer la pregunta en el idioma del código: una consulta en español sobre un código escrito en inglés da resultados mediocres, incluso cuando la respuesta está ahí.

Escribir la misma regla en tres sitios. Por el camino se formaron tres documentos: - la plantilla de ficha que rellenar, - el documento de método, - las instrucciones de trabajo que daba al agente.

Una misma regla — por ejemplo "una desviación nunca modifica el cuerpo de la ficha" — acabó escrita en los tres, cada vez con palabras algo distintas.

Mientras no cambia nada, no molesta a nadie. El día en que la regla evoluciona, corriges uno, olvidas los otros dos, y tres documentos se contradicen sin que nadie sepa cuál manda. Una IA menos que nadie: lee los tres sin ver que divergen y basa su análisis en el que ha abierto primero.

Cada regla vive ahora en un solo sitio. La plantilla de ficha describe únicamente la forma — qué campos, qué valores permitidos — y remite al método para todo lo demás. Una sola fuente por regla.

La ironía no me golpeó en ese momento: estaba construyendo un modelo de referencia destinado a eliminar las definiciones duplicadas, duplicando sus propias reglas en tres archivos.

Contar mal. Quería saber qué palabras usan realmente los clientes, y con qué frecuencia. Así que conté las ocurrencias de cada término de negocio en 261 notas de entrevistas.

Primer resultado: una sigla de dos letras aparecía 3.525 veces. En realidad había 2. La búsqueda contaba todas las veces en que esas dos letras estaban dentro de otra palabra. Busca "CA" de esa manera y cosechas "caso", "casa", "escáner", "aplicación".

Hay que contar palabras enteras, por tanto, y tener en cuenta las mayúsculas cuando el término es una sigla. Un contador falso es peor que ningún contador: tiene pinta de dato.

El error inverso también existe, y es más traicionero. Un término que creía ausente del producto sí estaba, pero usado en un sentido completamente distinto, en un rincón técnico sin relación con el negocio. Verifica una ausencia antes de concluir que algo falta.

Y una desviación que no lo era

Había registrado una desviación afirmando que cierto tipo de vínculo entre objetos no estaba correctamente descrito en el producto. Comprobado, sí lo estaba.

La desviación se queda en la ficha, marcada como rechazada, con el motivo del rechazo. Equivocarse forma parte del trabajo, con la condición de que el error deje un rastro utilizable — si no, alguien volverá a cometerlo dentro de seis meses.

El agente capta. El humano reabre.

El trabajo lo llevó a cabo un agente — una IA a la que se encarga una tarea larga — bajo mi dirección. Es probablemente la parte más transferible de este informe, porque no habla solo de ontología.

Una precisión de método: esta sección no se apoya en el recuerdo de nadie. El registro de decisiones del proyecto es el diario de mis intervenciones — cada entrada lleva su motivo, es decir, lo que corregí y por qué. El diario de avance muestra lo que el agente produjo entre dos arbitrajes. Todo lo que sigue se lee en esos dos rastros.

Lo que un agente hace notablemente bien: enumerar, cruzar, contar, mantener un seguimiento línea a línea y leer las traducciones de la duodécima área con la misma aplicación que las de la primera. Ese trabajo es masivamente repetitivo, y es exactamente lo que lo volvía inabordable hasta ahora.

Lo que hace mal: declarar el trabajo terminado. Los tres criterios de parada falsos no salieron de la nada — cada uno se propuso como prueba de conclusión, y cada vez hubo que rechazarlo. El sesgo es el mismo que en un humano cansado al final de un proyecto, salvo que él no tiene el cansancio como excusa: confundir informar con entregar.

Mis intervenciones, tal como se leen en los motivos de las decisiones, se ordenan en tres categorías:

• Ampliar un alcance que había reducido implícitamente. El agente leía el núcleo del código y se paraba ahí. La regla de los cuatro sitios, pantallas incluidas, viene de ahí — y es justamente en las pantallas donde están las desviaciones más interesantes.
• Corregir una estructura que iba a divergir. La misma regla escrita en tres sitios: la había copiado por afán de hacerlo bien, que era exactamente lo que no había que hacer.
• Rechazar un criterio de parada demasiado cómodo. Tres veces.

Lo que hace posible ese arbitraje se resume en cuatro dispositivos, y valen para cualquier trabajo delegado — a una máquina igual que a otra persona:

1. Un criterio de parada verificable por un tercero. No "lo he leído todo", sino una lista y una tasa.
2. Una medición que se puede volver a lanzar, en vez de una afirmación. Entre "está cubierto" y "aquí está el comando que lo verifica" está toda la distancia entre una promesa y un hecho.
3. Un seguimiento escrito, con la granularidad adecuada. Una línea por área y por sitio que leer, actualizada a medida. Sobrevive a la interrupción del trabajo, y es lo que evita hacer dos veces lo mismo.
4. La enumeración antes de la búsqueda. Lo que es seguro primero, lo que es probable después y como complemento.

52 objetos, y siete formas de verificar que no falta ninguno

Esto es lo que dio, una vez aplicado el criterio correcto.

52 objetos de negocio descritos. 250 reglas. 208 vínculos entre ellos. 124 desviaciones registradas. Ningún vínculo apuntando al vacío.

Las veinte preguntas de partida encuentran su respuesta sin abrir el código.

La cobertura, medida

El principio se resume en tres operaciones. Listo los objetos de un ángulo: los módulos, las tablas, los eventos, las pantallas, los recursos expuestos por la API. Miro, para cada uno, si corresponde a una ficha. Cuento.

La medición la vuelve a ejecutar un pequeño programa. Ese es el punto importante: no es una afirmación, es una comprobación que otra persona puede volver a lanzar.

Y es una medición débil, lo que hay que decir en la misma frase. El emparejamiento se hace por los nombres: una tabla sales_order se reconoce como la ficha "Sales Order", dejando de lado mayúsculas, guiones y plurales.

Eso funciona más o menos una vez de cada dos. En el resto, los nombres no se parecen en nada — una tabla puede llamarse so_header donde la ficha se llama "Sales Order". Así que mantuve al lado una lista de correspondencias, escrita línea a línea a medida que me topaba con los casos: esa tabla es ese objeto.

Esa lista es un juicio, no una regla. Si olvido una línea, el objeto sale como no cubierto cuando sí lo está. Si añado una dudosa — "venga, esa tabla tiene que corresponder a esa ficha" —, inflo mi propio marcador. E incluso cuando los nombres coinciden, puede ser casualidad: dos cosas distintas que llevan la misma palabra.

La medición, por tanto, no prueba nada. Señala dónde ir a mirar.

Por qué no busco llegar al 100 %

Es la objeción inmediata: si sé que me falta el 19 % de los módulos, sé cuáles son — solo hay que describirlos.

Salvo que la casilla que falta no es una tarea, es una pregunta. Cada objeto sin ficha es o un objeto de negocio que se me ha escapado, o parte puramente técnica sin ningún sentido de negocio: una cola técnica, un redimensionador de imágenes, una tabla de tokens de conexión, una pantalla de navegación. Llegar al 100 % supondría crear una ficha "Cola" y una ficha "Token" — es decir, contaminar el modelo de referencia para hacer subir una cifra.

El contador tiene por tanto tres estados, y no dos:

Lo que debe llegar al 100 % es la tercera línea a cero — nada que no haya sido examinado. El porcentaje mostrado, en cambio, no sube hasta 100 y no tiene por qué.

Aquí, el resto se ha revisado a mano: parte técnica, mecanismos internos, pantallas sin objeto de negocio propio. Ningún objeto de negocio se escondía ahí. Pero es una verificación manual, que hay que repetir en cada evolución — y esa es la debilidad que queda.

La cifra sirve entonces para otra cosa que medir un avance. Sirve para comparar los ángulos entre sí. 69 % en los objetos de la aplicación B contra 93 % en los eventos no quiere decir "queda el 31 % del trabajo": quiere decir "la aplicación B maneja cosas que el resto del producto desconoce, id a mirar por ahí". Ese desacuerdo es lo que hizo salir los cuatro hallazgos siguientes.

Lo que aportaron los ángulos

Cuatro objetos que ninguna otra vía habría encontrado:

• Por las tablas de la base. Un objeto que el producto muestra pero que no pertenece a ninguna área del código — en el ERP ficticio sería el vencimiento de facturación futuro: el cliente lo ve en su calendario de pagos, pero solo existe de verdad en el momento en que se emite la factura. Esa ambigüedad explica toda una familia de reclamaciones de clientes.
• Por los eventos. Un subconjunto entero de un área que creíamos cubierta, revelado por los eventos que emitía y que nadie había vinculado a nada.
• Por la API. Dos objetos repartidos en cinco módulos distintos — por tanto invisibles mientras avanzas área por área, y sin embargo expuestos contractualmente al exterior.
• Por la aplicación B. Dos objetos que maneja y que la aplicación A no conoce.

Los problemas que aparecen en todas partes

Aquí están los hallazgos, transpuestos al ERP ficticio. Son tipos de problema, no casos aislados — y apostaría a que ninguno falta en tu producto.

Un estado recalculado en todas partes, definido en ninguna. El estado de un pedido deducido de unas cuantas fechas y del estado de sus líneas, recalculado en cada pantalla, sin regla central. Dos pantallas acaban por no decir lo mismo, y nadie sabe cuál tiene razón.

Un objeto que el usuario ve y no puede reencontrar. El vencimiento de facturación del que hablaba: mostrado en el calendario de pagos, ausente de los resultados de búsqueda, porque todavía no existe como documento. El usuario, en cambio, lo ha visto en pantalla — así que lo busca, no lo encuentra y abre un ticket. El soporte responde caso por caso desde hace años sin que la causa esté escrita en ningún sitio.

Un valor que no lo es. El saldo de un cliente no es un número guardado en algún sitio: es el resultado de un cálculo sobre todas sus facturas, sus pagos, sus notas de crédito y sus apuntes de ajuste. Mientras eso siga implícito, cada nueva funcionalidad que "lee el saldo" se equivoca de objeto y da una cifra ligeramente distinta, según los movimientos que haya pensado incluir. Tres pantallas, tres saldos.

Una regla aplicada de un solo lado. El tope de descuento comprobado en el formulario de entrada, y en ningún otro sitio — por tanto esquivable por una importación de archivo o por la API. Es la máquina de desviaciones de la que hablaba arriba, y su rendimiento es notable.

Un permiso calculado a partir de seis fuentes sin ningún sitio que las reúna. El rol de la persona, el plan contratado, las opciones activadas, la restricción del periodo de prueba, el alcance de su filial, una lista de excepciones. Ningún sitio del producto dice "así se calcula un permiso". Cada evolución lo redescubre por su cuenta.

Un mismo objeto nombrado de forma distinta en cada piso. "Pedido" en pantalla, una palabra en el código, otra en la segunda aplicación, "negocio" en el terreno. Cuatro vocabularios para el objeto más central del producto.

Una palabra que los clientes usan sin parar y que el producto desconoce. En 261 notas de entrevistas, una noción vuelve 79 veces, otra 29. Ni una ni otra existe en el producto, bajo ningún nombre. No son diferencias de vocabulario, son carencias de concepción — y solo aparecen comparando lo que dicen los clientes con lo que hace el producto.

Los subproductos

Ninguno era el objetivo. Todos cayeron del trabajo.

Bugs candidatos. El producto contradice una expectativa escrita en algún sitio. Cada uno llega con su prueba y su consecuencia, no con una intuición.

Un vocabulario de cliente, con sus frecuencias. Contando las palabras en 261 notas de entrevistas y 365 tickets de soporte, se obtienen para cada objeto del producto los términos realmente empleados y su peso. Quien habla con el cliente sabe entonces qué palabra usar. Un término vuelve 168 veces para designar un alcance que el producto nombra de otra manera; otro, 141 veces para el objeto central.

Y esos dos corpus no dicen lo mismo. Las entrevistas dicen lo que los clientes quieren construir. Los tickets dicen lo que se rompe. Una misma palabra puede dominar uno y estar ausente del otro. Contarlos juntos es priorizar torcido.

Un estado de la cuestión de las traducciones. El glosario multilingüe solo cubre 15 de los 52 objetos. Entre los ausentes, dos sí se muestran al usuario en todos los idiomas: no existe traducción de referencia para ellos. Y de los diecinueve idiomas del glosario, solo dos se han revisado.

Lo que cuesta, y lo que el método sigue sin decir

El coste

Menos de seis horas. Es el tiempo que llevó el conjunto: las 52 fichas, las 250 reglas, las mediciones de cobertura. Una sesión, de principio a fin.

Antes de empezar había estimado unas cuantas decenas de horas, repartibles área por área. Me equivoqué en un orden de magnitud — y ese error de estimación es quizá la verdadera razón de que nadie hubiera hecho este trabajo antes: se cree fuera de alcance, así que no se empieza.

Tres reservas sobre esa cifra, para que siga siendo honesta. Es una medición sobre un producto, una vez, no una media. Las fuentes ya estaban reunidas e indexadas localmente; el tiempo de puesta en marcha no está incluido. Y dice tanto del utillaje como del método: el mismo trabajo a mano habría llevado semanas, que es justamente por lo que nunca se había hecho.

La condición de rentabilidad, en cambio, está clara: terminar un área antes de abrir otra. Un modelo de referencia completo sobre un alcance sirve de inmediato a todas las áreas que trabajan en ese alcance. Un modelo de referencia a medias sobre cinco alcances no sirve a nadie.

El mantenimiento

Es la pregunta que siempre se plantea en segundo lugar, y es legítima: un modelo de referencia del que no se dice cómo se mantiene vivo no interesa a nadie.

La versión de referencia hace de cursor: con un solo comando da la lista exacta de lo que se ha movido en el producto desde la última actualización — o sea, la lista de lo que queda por consignar.

Cada ficha lleva un diario donde se añaden entradas sin corregir nunca las anteriores. Una entrada que cita una versión del código señala que el producto ha cambiado. Una entrada que no cita ninguna señala otra cosa: es nuestra comprensión la que ha cambiado, no el producto. La distinción parece menor; es la que permite, seis meses después, saber si hemos corregido una ficha o si el software ha evolucionado.

Dos movimientos merecen mención porque ninguna herramienta los cuenta: la fusión de dos objetos que creíamos distintos y la división de un objeto que escondía dos. Son los movimientos más frecuentes cuando un modelo de referencia madura.

Por último, cuando un objeto se repiensa de arriba abajo, no modificamos su ficha: creamos una nueva y la antigua se queda. Describe lo que el producto ha sido, y sigue siendo necesaria para interpretar los datos y los intercambios anteriores al cambio.

Lo que decidí no hacer

• Ninguna reconstitución de la historia pasada del producto.
• Alcance cerrado en las exportaciones de datos, que son vistas derivadas del producto y no el producto en sí.
• Ningún utillaje erudito mientras ningún uso lo reclame.

Lo que el método todavía no dice

• Hasta dónde llevar el rigor del formato. Depende del uso, y el uso no ha empezado.
• Cómo vincular un dato antiguo al estado correcto de un objeto, cuando ese objeto se ha repensado entretanto.
• Quién revisa una ficha, y con qué criterios, antes de que entre en el modelo de referencia.
• A qué ritmo actualizar el punto de partida, y por tanto recuperar lo que se ha movido desde entonces.

Un documento de método que se pretende completo miente. Este lleva una sección "lo que todavía no dice", y se encoge a medida que las cuestiones se zanjan.

Conclusión: el criterio de parada es el verdadero entregable

Si tuviera que quedarme con una sola cosa de este proyecto, sería la frase que explica los tres falsos arranques:

Elegimos un criterio que podemos satisfacer, en vez de un criterio que prueba el trabajo hecho.

No concierne solo a las ontologías. Vale para una auditoría, una migración, una revisión de seguridad, una limpieza de deuda técnica. Cada vez que un trabajo termina con "lo he mirado todo", la pregunta que hay que hacer es: ¿todo, o sea qué? ¿Tienes la lista?

Dos comprobaciones, nunca una sola. Que el conjunto se sostiene se verifica mirando las fichas entre sí. Que está completo se verifica enumerando el producto. Confundirlas costó, aquí, un tercio del producto.

Queda lo más interesante, y no está hecho: las desviaciones. Todas esperan a ser instruidas — los bugs candidatos primero, luego los que ya apoya una petición de cliente, luego las faltas, luego la deuda de diseño. Eso ya no es descripción, es decisión de producto.

Es otro artículo, y solo podrá escribirse después.

Anexo A — Cómo es una ficha

Este anexo es la parte más técnica del artículo; se puede parar antes sin perder nada del argumento.

La ficha de abajo está transpuesta al ERP ficticio. Describe la forma — las reglas que la gobiernan viven en el documento de método, en un solo sitio.

Lo que contiene una ficha

La ficha en sí

El archivo lleva el nombre del objeto — es lo que permite que los vínculos entre fichas se resuelvan solos.

---
concept: Sales Order
definition: Compromiso de entrega asumido con un cliente, seguido desde su registro hasta su facturación.
parent:
enfants: ["[[Rush Order]]", "[[Standing Order]]"]
attributs:
  - nom: status
    type: enum
    valeurs: [draft, confirmed, shipped, invoiced]
relations:
  - verbe: placed-by
    cible: "[[Customer]]"
    cardinalite: 1..1
  - verbe: contains
    cible: "[[Order Line]]"
    cardinalite: 1..n
axiomes:
  - Un pedido facturado no puede recibir más líneas
lexique:
  fr: [commande, commande client]
  en: [sales order]
  es: [pedido]
  synonymes_terrain: [affaire, dossier]
  deprecies: [bon de commande client]
sources:
  - erp.sql:table `sales_order`
  - fr.json:order.status.draft
ecarts:
  - id: E1
    nature: manque
    portee: relations
    attendu: un vínculo hacia "[[Attachment]]", como el que tiene "[[Customer]]"
    consequence: imposible adjuntar un pedido de compra firmado
    statut: confirme
    date: 2026-08-10
historique:
  - date: 2026-08-10
    action: creation
    motif: descripción inicial, sobre la versión de referencia
---

# Sales Order

Compromiso de entrega asumido con un cliente, seguido desde su registro hasta su facturación.

## Vínculos

- *placed-by* → [[Customer]] (uno solo)
- *contains* → [[Order Line]] (al menos una)
- casos particulares → [[Rush Order]], [[Standing Order]]

## Historial

| Fecha | Qué ha pasado | Versión del código | Motivo |
|---|---|---|---|
| 2026-08-10 | creación | — | descripción inicial |

Una sola cosa está escrita dos veces: los vínculos. Una vez en la cabecera, para que las herramientas puedan leerlos; una vez en el cuerpo, para que aparezcan en la vista en red. Todo lo demás existe en un solo sitio.

Tres criterios de calidad, oponibles a cualquier ficha: la definición cabe en una frase y no se muerde la cola; cada vínculo está nombrado por un verbo preciso, nunca por "está relacionado con"; el vocabulario es multilingüe y lleva las palabras que usan los clientes.

Anexo B — La rejilla de las desviaciones

Lo que se anota para cada desviación:

Las cinco naturalezas:

Qué ocurre cuando la desviación desaparece. Se marca como resuelta, y se queda en la ficha. El cuerpo de la ficha se actualiza para describir la nueva realidad, y se añade una línea al diario. Los dos se responden: las desviaciones llevan la intención, el diario lleva el movimiento.

Un límite de seguridad. Una desviación describe una divergencia estructural, no un incidente. Una línea, un enlace al ticket. Las capturas de pantalla, los pasos de reproducción y el detalle se quedan en la herramienta de seguimiento. Una ficha no es un gestor de bugs.

Anexo C — Los ángulos de enumeración

Pasar por todos, y confrontarlos de dos en dos.

Tres reglas de uso:

1. La señal es el desacuerdo entre dos ángulos, no la puntuación de un ángulo tomado solo.
2. Cada objeto sin vincular se zanja explícitamente — objeto de negocio, o parte técnica. Nunca por omisión.
3. Dos corpus de cliente, contados por separado: las entrevistas dicen lo que los clientes quieren construir, los tickets lo que se rompe. Llevar las dos frecuencias al vocabulario — una orienta la roadmap, la otra la documentación y la formación.

Dónde están las reglas, en orden decreciente de rendimiento:

1. Los nombres de los mensajes de error técnicos. En las partes menos ordenadas del código suele ser la única fuente — y se lee sin saber programar.
2. Las comprobaciones hechas al inicio de una operación, antes de que se modifique nada.
3. Las restricciones de la base de datos — lo que debe ser único, lo que no puede quedar vacío. A veces contradicen el negocio, y esa diferencia es un defecto.
4. Las validaciones de entrada en las pantallas — la parte más olvidada, y la que produce las desviaciones más interesantes.

Un objeto descrito sin ninguna regla señala una descripción superficial, nunca un negocio sin reglas.