Que el grafo del conocimiento lo construya el que sabe del dominio
El conocimiento que de verdad importa en una organización suele estar en la cabeza de gente que no va a aprender markdown. En el equipo de psicólogos para el que monté una de estas wikis, lo que hay que registrar son años de entrevistas familiares y una biblioteca de terapia sistémica leída a fondo. Ninguno de ellos tiene por qué saber qué es un pull request, y no me parece un defecto suyo.
El planteamiento con el que trabajo estos corpus es que ahí no se acabe la conversación. El vocabulario y las validaciones se diseñan una vez, al principio, y a partir de ahí quien escribe es el que sabe del tema. El motor que lo sostiene lo conté por separado en el post del motor. Esto de aquí es la otra mitad, la que decide si el proyecto sirve: quién escribe, quién revisa y qué impide que aquello se degrade con el uso.
El cuello de botella no es escribir, es estructurar
Un experto escribe bien. Lo que no sabe —ni tiene por qué— es si lo que acaba de redactar es un concepto o una tesis, ni si la relación con esa otra nota se llama «cita» o «se apoya en». Son preguntas de bibliotecario, no de clínico.
Y cuando le dejas elegir la etiqueta, el problema no es que elija mal. Es que elige distinto cada martes. A las doscientas notas tienes sesenta etiquetas, la mitad sinónimas, y un grafo que ya no contesta nada porque dice sesenta cosas incompatibles a la vez.
La salida habitual es meter a un técnico en medio: el experto cuenta, el técnico estructura. Funciona, es cara y se rompe justo donde más duele, porque el técnico no distingue si dos conceptos del dominio son el mismo con distinto nombre. Ese papel lo he hecho yo en los tres corpus que llevo, así que hablo de algo que me ha costado horas.
Un vocabulario cerrado es un formulario, no una jaula
La wiki clínica funciona con nueve tipos de nota y siete etiquetas de relación. Eso es todo lo que un autor tiene que decidir, aparte de lo que quiere contar.
Suena a limitación y es lo contrario. Un editor rico te ofrece cuarenta opciones de formato y ninguna de significado: puedes poner el título en negrita, pero no puedes decir que esta nota contradice a aquella. Aquí va al revés. El formato da igual —es markdown— y lo único reglado es precisamente lo que después se puede preguntar.
El vocabulario cerrado no está para proteger el grafo del experto. Está para que el experto pueda escribir sin tener que preguntarle nada a nadie.
Lo que escribe realmente un autor
Una nota de ese corpus tiene esta forma. He traducido los nombres de relación a algo legible fuera de contexto, pero la estructura es literal: frontmatter con el tipo, una sección # Topology con las relaciones declaradas una a una, y a partir de ahí prosa normal.
---
type: tema
title: Pareja
---
# Topology
* **Se apoya en**: [[obras/el-arte-de-la-terapia-familiar]], [[obras/200-tareas-en-terapia-breve]]
* **Trata de**: [[conceptos/escalada-simetrica]], [[conceptos/simbiosis]]
* **Se distingue de**: [[temas/violencia-de-pareja]]
## La pareja como sistema
Escaladas simetricas, puntuaciones opuestas, simbiosis, y el lugar
del conflicto frente al de la violencia. De aqui abajo se escribe
como se escribe cualquier cosa.No hay JSON, ni base de datos, ni un formulario con veinte campos. Hay un fichero de texto donde las tres primeras viñetas son las que el grafo va a leer. El resto de la nota puede tener las páginas que haga falta.
El agente hace el andamiaje; el criterio lo pone el experto
De todo lo que hay que hacer para añadir una nota, casi nada requiere saber de terapia familiar: crear el fichero donde toca, poner el frontmatter, averiguar cómo se llaman exactamente las notas a las que apunta, pasar el validador y abrir la rama. Eso lo hace hoy sin dificultad un agente de programación con acceso al repositorio.
Lo que no es mecánico es una sola cosa: decidir que esta nota se apoya en aquella obra y no en la otra. Ahí no hay atajo, y es exactamente lo que el experto sabe y yo no.
El reparto se cae por su propio peso. El autor dicta en su idioma —«esto de las escaladas simétricas se apoya sobre todo en Watzlawick, y conviene separarlo de lo que decimos sobre violencia»— y el agente lo convierte en una nota que cumple el vocabulario, la valida en local y abre un pull request. El autor no llega a ver markdown: ve el sitio de vista previa que ese pull request publica, y dice sí o no.
Conviene que diga en qué punto está esto, porque el mecanismo es lo nuevo y lo demás no. Los tres corpus publicados los he destilado y editado yo, con agentes de programación como herramienta mía. Poner al experto en ese sitio, con el agente de intermediario, es el encargo que tengo cerrado y que arranca ahora. Lo que sí está probado y en producción es la capa de abajo —el vocabulario cerrado, el validador y el gate de publicación—, que es justo la que permite darle el teclado a alguien que no es técnico sin cruzar los dedos.
Que el intercambio pase por un pull request y no por un editor web tiene su razón: el pull request ya es un mecanismo de revisión, con autor, fecha, discusión y marcha atrás. Construir un editor propio habría sido hacer peor algo que ya existe.
Lo que revisa la máquina antes que nadie
Cada regla del validador tiene un nivel que el corpus puede subir o bajar. Son error el frontmatter que no parsea, la nota sin tipo y el tipo que se sale del set cerrado. Son aviso la etiqueta desconocida y la nota sin título. Una viene apagada a propósito, porque apuntar a una nota que todavía no existe es una forma legítima de dejar trabajo anotado.
Encima de eso, cada corpus pone su propio gate antes de publicar. El de la wiki clínica no despliega si el grafo baja de trescientos nodos o si falta alguno de los tres ficheros del visor. El del corpus público es este, literal:
test -f public/index.html || { echo "El build no genero public/index.html"; exit 1; }
for f in public/static/explorer.html \
public/static/okf-graph.json \
public/static/okf-explorer-access.js; do
test -s "$f" || { echo "falta el asset del grafo: $f"; exit 1; }
done
nodes=$(python3 -c "import json;print(len(json.load(open('public/static/okf-graph.json'))['nodes']))")Parece desconfianza excesiva hasta que te pasa. En la wiki clínica, un fallo de mi parser convirtió viñetas de la prosa en aristas tipadas que nadie había declarado; el grafo resultante se veía plausible, y lo que lo delató fue que las etiquetas no estaban en la lista cerrada. La historia completa está en el post del motor.
Esa es la razón de fondo por la que se le puede dar el teclado a alguien que no es técnico: no porque no vaya a equivocarse, sino porque sus errores tienen dónde chocar.
Qué gana el autor a cambio de la disciplina
El grafo de la portada es de ese corpus. El nodo seleccionado es «Pareja», y la ficha dice lo único que hace falta saber: siete obras y veintiuna notas entrantes. Eso ya es una pregunta contestada —en qué se apoya lo que este equipo sostiene sobre parejas, y qué parte de su propio material converge ahí—, y ningún buscador la contesta.
La segunda cosa que gana llega el día que entra material nuevo. okf-impact recorre el grafo y dice qué notas hay que revisar a partir de lo que se ha tocado. No es magia: es lo que se puede calcular cuando las relaciones están declaradas en lugar de inferidas.
Lo que todavía no está resuelto
- No he medido cuánto tarda un autor no técnico en soltarse. Mi apuesta es que la curva la marca el vocabulario, no la herramienta, y que un set de nueve tipos se aprende en una tarde. Es una apuesta, no un dato.
- El motor no está publicado como paquete. Se consume por tarball fijado por SHA y no tiene integración continua propia. Los consumidores sí tienen CI; el motor, no. La licencia MIT sí está, declarada en el package.json y con su LICENSE en la raíz.
- El diseño del vocabulario sigue siendo trabajo mío. Decidir qué nueve tipos describen un dominio es la mitad del proyecto y no se automatiza. Si alguien vende lo contrario, pregúntale por su lista de tipos.
Cuándo tiene sentido y cuándo no
Encaja si el conocimiento que sostiene tu trabajo está en personas y no en un sistema, si de ese material tienen que salir decisiones que alguien puede cuestionar, y si hay rotación —porque el día que se marcha quien más sabía, lo que queda es lo que se escribió.
No encaja si lo que necesitas es buscar dentro de mil PDFs. Para eso hay buscadores, y son más baratos que esto. La diferencia está en si te basta con encontrar el documento o necesitas saber en qué se apoya lo que dice.
Preguntas frecuentes
¿El experto tiene que aprender git?
No, y ese es el planteamiento. El agente crea la rama, valida y abre el pull request; el autor revisa el resultado en el sitio de vista previa que ese pull request publica. Lo que sí hay que aprender es el vocabulario: nueve tipos y siete relaciones en el corpus clínico. Eso no se puede delegar en nadie, porque es la parte que aporta el que sabe.
¿No es más rápido que un modelo extraiga las relaciones del texto?
Más rápido sí, y auditable no. Una relación inferida no se distingue de una inventada cuando miras el grafo dibujado: me pasó con un fallo de parser que metió aristas falsas y nadie lo vio hasta que las etiquetas chocaron con la lista cerrada. Las relaciones se declaran a mano; un agente ayuda a escribir la nota, pero lo que acaba en el grafo lo firmó una persona.
¿Qué pasa si un autor mete una relación que no existe?
El validador la rechaza con el nombre del fichero y la línea, y el sitio no se publica. Es lo que convierte la edición abierta en algo tolerable: el error se detecta antes de llegar a nadie, y el autor recibe un mensaje concreto en vez de un desastre silencioso.
¿De quién es el corpus si mañana dejamos de trabajar juntos?
Tuyo, y sin asteriscos. Son ficheros markdown en tu repositorio, con frontmatter, en un formato con especificación pública (OKF, de Google Cloud). El motor que los publica es código abierto en GitHub y se fija por SHA. Si desaparezco yo o desaparece la herramienta, el conocimiento se sigue leyendo con cat.
¿Tu conocimiento crítico lo tiene gente que no va a escribir documentación técnica?
Una biblioteca profesional, un archivo de casos, un criterio que hoy se transmite hablando. Cuéntame quién sabe y quién tendría que escribir, y te digo qué vocabulario le pondría y cuánto trabajo hay antes de que el equipo pueda editarlo solo.
Sobre grafos de conocimiento
Cómo crear tu propio grafo de conocimiento con quartz-okf
Del estándar al grafo y al proyecto
Huygens: un grafo en SurrealDB como memoria para agentes
