Llega una pregunta por Slack: ¿sabe hacer esto el producto, 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 sobre el terreno, que hay que responder en menos de una hora. Así que alguien abre un entorno de pruebas, reproduce el caso, comprueba. Media hora. Pagada dos veces: por quien busca, y por la persona a la que interrumpe.

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 gobiernan, las palabras para hablar de ellos— no está escrito en ningún sitio de 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: varias decenas de objetos descritos, unos cientos de reglas, otros tantos enlaces entre ellos. Este artículo cuenta cómo lo conseguí, y sobre todo lo que fallé por el camino, porque esa es la parte que se puede transferir.

Tres advertencias antes de empezar.

La primera: esta experiencia trata de la fabricación del repositorio, no de su uso. Existe, está medido, ya ha dado sus primeros subproductos. Pero la fase de explotación no ha empezado. Por tanto 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 están tomados de un caso ficticio: una empresa que edita 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, sino el tipo de problema que se encuentra: un estado recalculado en todas partes y definido en ninguna, una regla aplicada por 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 relato, no un post: he preferido contarlo todo antes que ser breve. Si solo vas a leer una sección, quédate con «Tres criterios de parada. Tres veces falsos.»: lo demás es el contexto que la rodea. Los anexos, por su parte, solo sirven a quien quiera rehacer el trabajo.

Una ontología no es un glosario ampliado

La palabra es una trampa. A unos les evoca la filosofía, a otros un campo técnico con sus herramientas complicadas, y a la mayoría nada en absoluto. Mejor dejarlo claro desde el principio.

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 relaciona, - lo que es cierto sobre ellos, - las palabras con las que los designamos.

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

En el resto del artículo, para evitar los términos técnicos, digo «objetos», «propiedades», «enlaces», «reglas» y «palabras». Es lo mismo.

Esas cinco casillas sirven además de filtro: lo que no entra en ninguna no tiene nada que hacer en el repositorio.

Por qué un documento más

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

Lo que los distingue de una ontología se resume en un punto: ahí los enlaces cuentan tanto como las definiciones. Un objeto descrito por sí solo no enseña gran cosa. Ese mismo objeto enlazado con otros cinco mediante verbos precisos —realizado 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 distancia entre ellos es información valiosa. El repositorio la conserva: la palabra oficial, las palabras que usan los clientes y las que se abandonaron por el camino. Es lo que permite traducir una frase de usuario a un objeto del producto, y al revés.

Lo que no hice

Existen formas muy sofisticadas de hacer todo esto: lenguajes dedicados, herramientas que deducen conclusiones a partir de las reglas que se les dan, normas que van con ello. Es un campo de verdad, y no entré en él (entre otras cosas, por falta de competencias).

Empecé por lo que sabía manejar: una ficha por objeto, en un archivo de texto. Un título, unos cuantos campos, enlaces hacia las demás fichas. Nada que un editor de texto no sepa abrir. Mientras no sepa para qué va a servir el repositorio, no sé qué nivel de rigor necesito, y empezar simple para complicarse más tarde siempre sale más barato que lo contrario.

El código se ha convertido en la fuente de verdad. El sentido se ha quedado fuera.

Alrededor de este producto, una parte creciente de lo que lo describe se regenera a partir del código. El razonamiento es simple: la verdad de un producto es lo que funciona, no lo que se había previsto.

Ese cambio elimina un trabajo entero: el de 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, en cambio, se construye por encima.

Tomemos el pedido, y su estado. El código da la estructura: aquí están los campos, aquí los valores posibles. Hay cuatro informaciones que lo hacen realmente aprovechable, y ninguna está ahí:

• la regla: un pedido facturado ya no admite líneas nuevas. El producto la aplica, pero la regla no está escrita en ninguna parte: la comprobación está repartida por cinco archivos y cada uno hace solo un trozo. Para enunciarla en una frase hay que haberlos leído los cinco;
• los casos particulares: un pedido urgente es un pedido, con restricciones añadidas;
• el vocabulario: los usuarios dicen «asunto», 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.

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

El coste real se paga en otro sitio

La pregunta del principio es solo un caso entre muchos. Todo lo que describe el producto a alguien es una reconstrucción, rehecha cada vez, en paralelo, por cada departamento: la documentación, las respuestas a las licitaciones, la formación de quienes se incorporan, el discurso del soporte. Cada uno parte de cero desde el código, o desde la memoria de alguien.

Ese es el gasto que se trata de eliminar. No aparece en ningún presupuesto, y eso explica que llevemos años pagándolo sin verlo.

Una IA no puede preguntar. Adivina.

Hasta ahora, lo que el producto es de verdad se transmitía de viva voz. Se preguntaba a la persona adecuada, se obtenía la regla, uno seguía con lo suyo. El modelo del producto vivía en unas cuantas 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, se la describes en unas pocas frases. En nuestra cabeza hay un modelo completo: qué es un pedido, por qué estados pasa, qué está prohibido y a partir de cuándo. El agente solo tiene nuestras pocas frases, más lo que consiga leer en el código. El resto lo rellena, de forma plausible, coherente y a veces falsa.

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

Un repositorio es ese modelo mental escrito. Dárselo a un agente no lo hace más inteligente: le impide inventar allí donde 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 a los pedidos.» Con el repositorio en contexto, el agente sabe que un pedido facturado ya no admite líneas nuevas, que un descuento tiene un tope y que «pedido» incluye también los pedidos urgentes y los pedidos recurrentes. Sin él, descubrirá una de esas tres cosas al revisar el resultado, y eso en el mejor de los casos.

Analizar más rápido. Investigar un bug empieza siempre por reconstruir el modelo de la zona afectada. Esa reconstrucción se rehace cada vez, por cada persona y por cada agente. Escrita una sola 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 lugar de rebuscar al azar.

Escribir las pruebas y arbitrar las incidencias. Una regla es una afirmación verificable. «Un pedido facturado ya no admite líneas nuevas» es una prueba, tal cual, formulada en lenguaje de negocio. Unos cientos de reglas son otros tantos casos de prueba candidatos que nadie tiene que deducir del código. Y ante una incidencia de un cliente, la pregunta se vuelve mecánica: ¿contradice 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, a cargo de la persona más veterana del equipo.

Nada de esto está medido, de acuerdo con 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 repositorio en contexto y la otra mitad sin él, comparar el tiempo invertido 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

Hay un dilema desde el primer momento. Sin un modelo, aunque sea tosco, no sabes qué material recoger, y se te escapan informaciones importantes sin enterarte. Sin material, no sabes qué modelo sostener.

Iterar, no secuenciar. Se esboza lo justo para saber qué buscar, se busca, se retoma el modelo con lo aprendido. Una restricción atraviesa esas idas y venidas: lo que se recoge se guarda en la forma más simple posible, y siempre con la indicación de su procedencia. Un cambio de modelo nunca debe obligar a volver a buscar lo que ya se tiene.

Por dónde empezar: una veintena de 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 repositorio deberá saber responder, y ellas delimitan el terreno. El problema es que unas preguntas escritas en frío, en una sala de reuniones, se parecen siempre a lo que creemos que es importante.

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

Las preguntas de producto que nos llegan se archivan con su respuesta. Las releí todas y luego las condensé en una veintena de preguntas genéricas. Ninguna sale de mi imaginación: cada una engloba un conjunto de preguntas realmente formuladas.

Trasladadas 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 a partir de qué momento ya no?
• ¿Qué es el saldo de un cliente, y con qué movimientos evoluciona?
• ¿A quién corresponde un pedido generado automáticamente, y qué pasa 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; basta con contar. Más de la mitad de las preguntas apuntaban a la misma: pasó a ser la primera. El resto se repartía entre otras dos. El orden deja de ser una preferencia y pasa a ser un recuento.

Y sirven una segunda vez, al llegar a la meta. Una vez terminada un área, se retoman sus preguntas y se comprueba que el repositorio las responde sin abrir el código. El control hecho a mitad de camino solo dejó dos preguntas sin respuesta completa. Las dos que faltaban lo estaban de la misma manera: una regla escrita en general allí donde la pregunta esperaba el detalle, «ciertas operaciones exigen esto» sin decir nunca cuáles.

Es el fallo más probable en este tipo de trabajo, y el más difícil de ver. Contar las fichas no lo habría mostrado jamás.

Una ficha por objeto, y enlaces entre ellas

Una ficha por objeto del negocio, en un archivo de texto con su nombre. Cada vez que una ficha menciona otro objeto, lo hace mediante un enlace.

Parece un detalle cosmético. No lo es. Las fichas y sus enlaces forman una red, y esa red se puede visualizar: cada ficha es un punto, cada enlace una línea. Un enlace 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 para convertirse en la cola de trabajo: mientras queden enlaces al vacío, quedan fichas por escribir.

La realidad por un lado, la intención por otro

Un repositorio 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 no permite nunca sacar a la luz un defecto. La segunda pierde el rastro de lo que existe de verdad.

Me quedo con 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 aparte, al final de la ficha, enumera las desviaciones: cada punto en el que 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 vida útil:

El cuerpo se deduce del código: se puede tirar y rehacer sin perder nada. Las desviaciones, en cambio, llevan juicio dentro; si se pierden, no se recuperan en ninguna parte. Separarlas es proteger la parte que cuesta cara de producir.

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

Bastan cinco tipos de desviación, y son ellos los que convierten el repositorio 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 gira 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 sale en ella es el estado inicial, sin fecha de nacimiento: no intento averiguar cuándo apareció cada campo. Reconstruir la historia del producto obligaría a rebuscar en años de archivo para un beneficio nulo.

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

Lo único que hay que vigilar, y ahí me pillaron: una fuente que no procede de la foto no es una fuente. Vuelvo a ello 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 no está terminada hasta que se han leído los cuatro. Una regla puede perfectamente existir solo en uno.

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

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

O bien es una regla de negocio de verdad, mal colocada: una molestia. O bien se puede esquivar pasando por fuera de la pantalla, mediante una importación de archivo o mediante la interfaz que el producto expone a los desarrolladores externos, su API. Y entonces es un defecto, con un problema de seguridad detrás: lo que la pantalla prohíbe, otro camino lo permite.

El caso contrario 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 observaciones sobre esta lectura de las pantallas.

Primero, la división de las pantallas no coincide con la del código. Varias zonas de la interfaz no tenían zona equivalente del lado del servidor. El cotejo se hace, por tanto, objeto por objeto, nunca carpeta por carpeta.

Segundo, un truco que vale oro en las partes del código peor ordenadas: 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 modificar un pedido facturado»— enuncia por sí solo una regla. Basta con leer la lista de esos nombres, y eso 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 un oficio establecido, con su bibliografía, y el método anterior no hace más que retomar cosas ya sabidas:

• Lo iterativo antes que la cascada. Los métodos históricos encadenaban las etapas en orden: especificar, diseñar, formalizar, construir. Los desbancaron enfoques por pequeñas piezas recombinables. El debate está zanjado desde hace unos quince años.
• El encuadre por preguntas. Escribir primero las preguntas a las que el repositorio deberá responder es el dispositivo estándar; incluso tiene nombre, competency question. Ir a buscarlas al soporte en lugar de escribirlas en frío no está en los manuales. No cuesta nada, y cambia lo que encuentras.
• Empezar por el 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 formas de hacerlo 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 desproporcionado respecto a la necesidad.
• El 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 que son referencia. Hay que mirarlas, y tratar cualquier divergencia entre el modelo propio y ellas como una cuestión que investigar, no como un detalle.

Tres criterios de parada. Tres veces falsos.

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

Antes, dos estrategias descartadas

Saber qué buscar no dice en qué orden recorrer el producto. Se presentan dos enfoques 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 guarda ninguna relación con la importancia de negocio, y lo que está ahí solo por motivos técnicos queda descrito al mismo nivel que los objetos de negocio de verdad. Acabas con un montón 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 del negocio. Muchas tablas solo sirven para relacionar otras dos, para guardar un rastro técnico, para almacenar tokens de sesión o resultados temporales. No tienen ningún sentido para quien habla del producto.

Así que opté por una tercera vía: un área del producto cada vez, yendo del núcleo del negocio hacia la periferia, apoyándome en la división que el código ya trae. Un software un poco grande está dividido en módulos: zonas de código que se corresponden a grandes rasgos con áreas del negocio, la facturación, las compras, los permisos de acceso. Esa división la hicieron desarrolladores, pero ya constituye una descripción parcial del negocio, gratis 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, ya no hay ningún enlace que apunte al vacío. Luego está 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 una minoría de los módulos había dado lugar a una ficha.

Lo que ese control demostraba realmente: que el conjunto se sostiene. Nada más. Es un buen control, hay que conservarlo, pero no responde a la pregunta planteada.

El control de cobertura que hice a continuación sacó a la luz dos objetos centrales del negocio que nada, dentro de la red, reclamaba.

Segundo criterio: «he recorrido todas mis fuentes»

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

Es cierto, y no demuestra nada. Es una afirmación sobre lo que he abierto, no sobre lo que existe. «He leído toda mi pila» 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.

También es cierto, e insuficiente por la misma razón: solo vale para las áreas que yo había identificado. El criterio mide la profundidad, no dice nada de la anchura. Se pueden leer cuatro sitios sobre una minoría de los módulos e ignorar todo lo demás, que es exactamente lo que pasó.

El diagnóstico

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

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

Uno elige un criterio que puede satisfacer, en lugar de un criterio que demuestre el trabajo hecho.

Es la diferencia entre «he recogido todo lo que estaba tirado por el escritorio» y «aquí está la lista de lo que tenía que recoger, todo marcado». La primera frase es verdad, y no compromete a nada. La segunda supone haber hecho la lista antes de empezar.

No es deshonestidad, es una cuestión de coste.

Un criterio que se puede satisfacer ya está a mano: basta con mirar lo que acabas de hacer y constatar que está hecho. Un criterio que demuestra, en cambio, exige fabricar algo más: la lista de lo que existe, una forma de contarla, una cifra que otra persona pueda recalcular. Es trabajo adicional, reclamado justo en el momento en que crees haber terminado.

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

El único criterio que se sostiene

Enumerar el producto desde varios ángulos independientes, y medir para cada uno la proporción que se corresponde con 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 bien un objeto del negocio que se nos ha escapado, o bien mecánica interna. La cuestión se resuelve en una línea, pero se resuelve explícitamente, nunca pasando de largo.

Los demás errores

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

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

La regla es más simple de lo que yo creía en ese momento. No es «comprobar la fecha antes de concluir», es que una fuente que no procede de la foto no es una fuente. O se sustituye por una versión al día, o se prescinde de ella.

Y la precisión que importa, porque al principio se me había escapado: cuando dos partes de la misma foto se contradicen —el código por un lado, la base o la pantalla por 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 significado, el principio del RAG: haces la pregunta en lenguaje corriente y la herramienta saca los pasajes que más se le acercan. Es tremendamente eficaz para recuperar una regla enterrada en mitad de un archivo, que nada en su nombre delataba.

Pero un motor de ese tipo responde siempre, y responde siempre con una clasificación: aquí tienes los diez pasajes más próximos a tu pregunta. Nunca dice «no hay ninguno». Una búsqueda que no trae nada interesante puede significar por tanto dos cosas: que la cosa no existe, o que he planteado mal la pregunta. Imposible decidir.

De ahí la regla: enumerar primero, buscar después. En el otro sentido, obtienes un repositorio hecho de lo que el motor haya tenido a bien sacar.

Dos detalles que salen caros. El motor tenía su propia fecha, una versión de retraso respecto al código. Y hay que plantear la pregunta en el idioma del código: una consulta en francés sobre un código escrito en inglés da resultados mediocres, incluso cuando la respuesta está ahí.

Escribir la misma regla en tres sitios. Sobre la marcha se fueron formando tres documentos: - la plantilla de ficha que hay que rellenar, - el documento de método, - las instrucciones de trabajo que yo le 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 se cambia nada, no molesta a nadie. El día en que la regla evoluciona, corriges uno, te olvidas de 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 su momento: estaba construyendo un repositorio 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 apariciones de cada término de negocio en varios cientos de actas de entrevistas.

Primer resultado: unas siglas de dos letras aparecían varios miles de veces. En realidad había dos. La búsqueda contaba todas las veces en que esas dos letras se encontraban dentro de otra palabra. Busca «CA» de esa manera y te traes «cadena», «casa», «escaparate», «aplicación».

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

El error inverso también existe, y es más traicionero. Un término que yo 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. Comprobar una ausencia antes de concluir que hay una carencia.

Y una desviación que no lo era

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

La desviación se queda en la ficha, marcada como rechazada, con el motivo del rechazo. Equivocarse forma parte del trabajo, a condición de que el error deje un rastro aprovechable; si no, otra persona repetirá el mismo dentro de seis meses.

El agente recoge. El humano reabre.

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

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 extraordinariamente bien: enumerar, cruzar, contar, mantener un seguimiento línea a línea, y leer las traducciones del área número doce con el mismo esmero que las de la primera. Este trabajo es masivamente repetitivo, y eso es precisamente lo que lo hacía inabordable hasta ahora.

Lo que hace mal: declarar el trabajo terminado. Los tres criterios de parada falsos no salieron de la nada: los propuso él como prueba de finalización, y cada vez hubo que rechazarlos. El sesgo es el mismo que el de 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 agrupan en tres categorías:

• Ampliar un alcance que él 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 o a otra persona:

1. Un criterio de parada verificable por un tercero. No «lo he leído todo», sino una lista y un porcentaje.
2. Una medición que se puede volver a lanzar, en lugar de una afirmación. Entre «está cubierto» y «aquí está el comando que lo comprueba» hay toda la distancia que separa una promesa de un hecho.
3. Un seguimiento escrito, con el nivel de detalle adecuado. Una línea por área y por sitio que leer, actualizada sobre la marcha. Sobrevive a la interrupción del trabajo, y es lo que evita hacer dos veces lo mismo.
4. La enumeración antes que la búsqueda. Primero lo seguro, después y como complemento lo probable.

El resultado, y siete formas de comprobar que no falta nada

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

Varias decenas de objetos del negocio descritos. Unos cientos de reglas. Otros tantos enlaces entre ellos. Numerosas desviaciones detectadas. Ningún enlace que apunte ya al vacío.

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

La cobertura, medida

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

Los siete ángulos elegidos: los módulos de la aplicación A, las tablas de la base de datos, los eventos que emite el software, las pantallas de la aplicación A, los módulos y los objetos de la aplicación B, los recursos que expone la API.

Los porcentajes obtenidos van del 70 al 95 % según el ángulo.

La medición se puede repetir con un pequeño programa. Ese es el punto importante: no es una afirmación, es un control que otra persona puede volver a lanzar.

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

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 allí donde la ficha se llama «Sales Order». Así que mantuve aparte una lista de correspondencias, escrita línea a línea a medida que me las iba encontrando: esta tabla es este objeto.

Esa lista es un juicio, no una regla. Si me dejo una línea, el objeto sale como no cubierto aunque lo esté. Si añado una dudosa —«venga, esta tabla tiene que corresponder a esta ficha»—, estoy inflando mi propia puntuación. E incluso cuando los nombres coinciden, puede ser casualidad: dos cosas distintas con la misma palabra.

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

Por qué no busco llegar al 100 %

Es la objeción inmediata: si sé qué proporción de módulos no tiene ficha, sé cuáles son; basta con describirlos.

Salvo que la casilla vacía no es una tarea, es una pregunta. Cada objeto sin ficha es o bien un objeto del negocio que se me ha escapado, o bien mecánica interna sin ningún sentido de negocio: una cola técnica, un redimensionador de imágenes, una tabla de tokens de sesión, una pantalla de navegación. Llegar al 100 % supondría crear una ficha «Cola» y una ficha «Token», es decir, contaminar el repositorio 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: que no quede nada sin examinar. El porcentaje que se muestra, en cambio, no sube hasta 100 ni tiene por qué hacerlo.

Aquí, el resto se revisó a mano: cosas técnicas, mecanismos internos, pantallas sin objeto de negocio propio. No se escondía ningún objeto del negocio. Pero es una comprobación manual, que hay que rehacer en cada evolución, y esa es la debilidad que queda.

La cifra sirve, pues, para otra cosa que para medir un avance. Sirve para comparar los ángulos entre sí. El más bajo de los siete porcentajes, sobre los objetos de la aplicación B, frente al más alto, sobre los eventos: la diferencia no quiere decir «queda todo este trabajo por hacer», quiere decir «la aplicación B maneja cosas que el resto del producto desconoce, id a mirar por ahí». Ese desacuerdo es el que sacó a la luz 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 no existe de verdad hasta 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 se creía cubierta, revelado por los eventos que emitía y que nadie había vinculado a nada.
• Por la API. Unos cuantos objetos repartidos por varios módulos, por tanto invisibles mientras se avanza á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 desconoce.

Los problemas que aparecen en todas partes

Estos son los hallazgos, trasladados al ERP ficticio. Son tipos de problema, no casos aislados, y me apostaría algo 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 encontrar. El vencimiento de facturación del que hablaba: se muestra en el calendario de pagos, no aparece en 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 lleva años respondiendo caso por caso sin que la causa esté escrita en ninguna parte.

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 abonos y sus asientos 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 se le haya ocurrido incluir. Tres pantallas, tres saldos.

Una regla aplicada por un solo lado. El tope de descuento controlado en el formulario de entrada, y en ningún otro sitio, luego esquivable mediante una importación de archivo o mediante la API. Es la máquina de desviaciones de la que hablaba más 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 vuelve a descubrirlo por su cuenta.

Un mismo objeto con un nombre distinto en cada nivel. «Pedido» en la pantalla, una palabra en el código, otra en la segunda aplicación, «asunto» sobre 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 ese corpus de entrevistas, una noción aparece varias decenas de veces, otra algo menos. Ni una ni otra existen en el producto, bajo ningún nombre. No son diferencias de vocabulario, son carencias de diseño, y solo salen a la luz 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 alguna parte. Cada uno llega con su prueba y su consecuencia, no con una intuición.

Un vocabulario de cliente, con sus frecuencias. Contando las palabras sobre un corpus amplio de actas de entrevistas y de tickets de soporte, se obtienen para cada objeto del producto los términos realmente usados y su peso. Quien habla con el cliente sabe entonces qué palabra emplear. Un término aparece más de cien veces para designar un alcance que el producto llama de otra manera; otro, casi otras tantas, 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 al revés.

Un estado de situación de las traducciones. El glosario multilingüe solo cubre una minoría de los objetos descritos. Entre los ausentes, algunos sí se muestran al usuario en todos los idiomas: no existe para ellos ninguna traducción de referencia. Y del conjunto de los idiomas del glosario, solo se ha revisado una pequeña parte.

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

El coste

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

Antes de empezar había estimado unas 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 por la que nadie había hecho antes este trabajo: 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 en local; el tiempo de preparación no está incluido. Y dice tanto de las herramientas como del método: el mismo trabajo a mano habría llevado semanas, y precisamente por eso nunca se había hecho.

La condición de rentabilidad, en cambio, está clara: terminar un área antes de abrir otra. Un repositorio completo sobre un perímetro sirve de inmediato a todos los departamentos de ese perímetro. Un repositorio a medio hacer sobre cinco perímetros no le sirve a nadie.

El mantenimiento

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

La versión de referencia sirve de marcador: da, con un simple comando, la lista exacta de lo que ha cambiado en el producto desde la última actualización, es decir, la lista de lo que queda por registrar.

Cada ficha lleva un diario en el que 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 la cita señala otra cosa: lo que ha cambiado es nuestra comprensión, no el producto. La distinción parece menor; es la que permite saber, seis meses después, 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 se creían distintos, y la división de un objeto que escondía dos. Son los movimientos más frecuentes cuando un repositorio madura.

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

Lo que he decidido no hacer

• Nada de reconstruir la historia pasada del producto.
• Perímetro cerrado en las exportaciones de datos, que son vistas derivadas del producto y no el producto en sí.
• Nada de herramientas sofisticadas mientras ningún uso las 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 replanteado entretanto.
• Quién revisa una ficha, y con qué criterios, antes de que entre en el repositorio.
• Con qué ritmo actualizar el punto de partida, y por tanto recuperar lo que ha cambiado desde entonces.

Un documento de método que presume de estar completo miente. Este lleva una sección «lo que todavía no dice», y encoge a medida que las preguntas se van resolviendo.

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 arranques en falso:

Uno elige un criterio que puede satisfacer, en lugar de un criterio que demuestre el trabajo hecho.

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

Dos controles, nunca uno solo. Que el conjunto se sostenga se comprueba mirando las fichas entre sí. Que esté completo se comprueba enumerando el producto. Confundirlos ha costado aquí una parte importante del producto.

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

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

Anexo A — Qué aspecto tiene una ficha

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

La ficha de abajo está trasladada 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 enlaces entre fichas se resuelvan solos.

---
concepto: Sales Order
definicion: Compromiso de entrega adquirido con un cliente, seguido desde su registro hasta su facturación.
padre:
hijos: ["[[Rush Order]]", "[[Standing Order]]"]
atributos:
  - nombre: status
    tipo: enum
    valores: [draft, confirmed, shipped, invoiced]
relaciones:
  - verbo: placed-by
    destino: "[[Customer]]"
    cardinalidad: 1..1
  - verbo: contains
    destino: "[[Order Line]]"
    cardinalidad: 1..n
axiomas:
  - Un pedido facturado ya no puede recibir líneas
lexico:
  fr: [commande, commande client]
  en: [sales order]
  es: [pedido]
  sinonimos_terreno: [asunto, expediente]
  obsoletos: [nota de pedido de cliente]
fuentes:
  - erp.sql:tabla `sales_order`
  - fr.json:order.status.draft
desviaciones:
  - id: E1
    tipo: carencia
    alcance: relaciones
    esperado: un enlace hacia "[[Attachment]]", como tiene "[[Customer]]"
    consecuencia: imposible adjuntar un pedido firmado
    estado: confirmada
    fecha: 2026-08-10
historial:
  - fecha: 2026-08-10
    accion: creacion
    motivo: descripción inicial, sobre la versión de referencia
---

# Sales Order

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

## Enlaces

- *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 |

Solo hay una cosa escrita dos veces: los enlaces. Una vez en la cabecera, para que las herramientas puedan leerlos; otra en el cuerpo, para que aparezcan en la vista en red. Todo lo demás existe en un solo sitio.

Tres criterios de calidad, exigibles a cualquier ficha: la definición cabe en una frase y no se muerde la cola; cada enlace está nombrado con un verbo preciso, nunca con «está relacionado con»; el vocabulario es multilingüe y recoge las palabras que usan los clientes.

Anexo B — La plantilla de las desviaciones

Lo que se anota para cada desviación:

Los cinco tipos:

Qué pasa 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 complementan: las desviaciones llevan la intención, el diario lleva el movimiento.

Una salvaguarda. Una desviación describe una divergencia estructural, no una incidencia. Una línea, un enlace al ticket. Las capturas de pantalla, los pasos para reproducirla 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

Hay que pasarlos 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 por sí solo.
2. Cada objeto no vinculado se resuelve explícitamente: objeto del negocio, o mecánica interna. Nunca por omisión.
3. Dos corpus de clientes, contados por separado: las entrevistas dicen lo que los clientes quieren construir, los tickets lo que se rompe. Llevar las dos frecuencias en el vocabulario: una orienta la roadmap, la otra la documentación y la formación.

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

1. Los nombres de los mensajes de error técnicos. En las partes del código peor ordenadas suele ser la única fuente, y se lee sin saber programar.
2. Las comprobaciones que se hacen 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 al negocio, y esa divergencia es un defecto.
4. Las validaciones de entrada en las pantallas: la parte que más se olvida, 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.