Expertos

Un experto es una carpeta de contexto que se pega dentro del prompt de una etapa. Las reglas sobre qué puede entrar ahí son la parte interesante.

tldrx init te los siembra y nunca pregunta. Cuántos, depende de lo que haya encontrado la detección — aquí, un solo lenguaje y ninguna carpeta de código que el mapa leyera como dominio:

expert            status   last_trained  areas  evidence  levels
----------------  -------  ------------  -----  --------  ------
architect         created  never         1      0         0
delivery          created  never         1      0         0
developer         created  never         1      0         0
javascript-stack  created  never         1      0         0
operations        created  never         1      0         0
product           created  never         1      0         0

architect — created
  loaded by: how (named), plan (named)
  architect  ☆☆☆☆☆ 0  (no evidence)

Se siembran tres clases. Cinco expertos de rol, siempre: product para What, architect para How y Plan, delivery para Plan, developer para Build, operations para Watch; los archivos de etapa los nombran, así que no dependen de la detección. Luego un experto de stack por lenguaje, detectado o declarado — dos lenguajes son dos de ellos, y por eso el conteo de arriba es un piso y no una regla. Y luego un experto de dominio por cada carpeta de código de primer nivel que el mapa leyó como dominio, con tope de ocho para que un monorepo grande no acabe con cincuenta esbozos que nadie entrena. El repo de arriba no tenía ninguno que sembrar; uno de verdad casi siempre sí.

Todos arrancan en nivel 0, y un experto en nivel 0 no está roto: aporta la descripción de su rol y nada más.

Qué trae uno adentro

.tldrx/experts/billing/
  expert.md              el rol, el dominio que le toca y sus reglas de cita — esto lo escribió una persona
  competencies.yml       una línea por área, calculada de la evidencia, nunca autodeclarada
  knowledge/money.md     lo que encontró el entrenamiento, cada punto con su fuente

La tabla de estrellas es la parte honesta:

ef-core  ★★★☆☆ 3  (17 evidence, newest 2026-08-20)

Un nivel se mueve porque se citó un archivo, nunca porque un agente dijo que aprendió algo. Nada de lo que un experto afirme sobre sí mismo cambia su número.

Qué expertos carga una etapa

Tres reglas, y nada más tres:

1. la etapa lo nombra (experts: en stage.yml);
2. es el experto <language>-stack de alguno de los repos del run;
3. es un experto de dominio cuyas rutas declaradas el run sí cita — o que queda a dos saltos de una ruta citada en el grafo del código.

tldrx expert list imprime una línea loaded by: por cada uno — how (named), plan (named) — para que un experto entrenado que ninguna etapa va a cargar jamás deje de ser invisible.

Todos los expertos cargados comparten un solo presupuesto de conocimiento de 48 KB, repartido según qué tan relevante es cada uno para este run, en vez de darle uno propio a cada quien. Los archivos que la etapa declaró como entradas se llenan primero: una entrada que la etapa pidió le gana a material de referencia que nadie pidió.

Packs de stack

Un experto <language>-stack arranca como un esbozo, sin nada específico del stack adentro. Prende los packs de stack y recibe un cuerpo que ya viene con la herramienta — TypeScript, JavaScript, Python o .NET — más un overlay por cada framework que tus manifiestos demuestren. Vienen trece: react, next-app-router, vite-react-spa, expo-router, node-express, prisma, aspnet-minimal-apis, aspnet-controllers, mediatr-cqrs, efcore-npgsql, fastapi, sqlalchemy-alembic y postgres-testcontainers.

tldrx expert packs enable     # un solo interruptor, apagado por defecto
tldrx expert packs status     # overlays con su evidencia, skills, y el estado de cada cuerpo
tldrx expert packs disable    # quita los overlays; los cuerpos y el conocimiento se quedan

Los overlays se leen del package.json, de los .csproj y del Directory.Packages.props, del pyproject.toml o de un requirements*.txt — nunca del nombre del lenguaje, porque dos proyectos en el mismo lenguaje pueden estar construidos sobre arquitecturas opuestas. Cada uno que se detecta queda escrito en workspace.yml con la línea que lo demostró, esté el interruptor prendido o no: la detección es una medición, y el interruptor solo decide si los archivos se escriben.

Un pack es interrogativo. Sus Checks son preguntas que se le hacen a cada diff, cada una con una pista verify: de qué abrir o qué correr; sus Defaults aplican solo donde tu repo no dice nada, y cada uno nombra la señal que lo anula. Las convenciones de tu repo ganan — un pack que discutiera con ellas sería peor que ningún pack. El revisor de Build no ve ningún cuerpo de experto, así que esos Checks le llegan bajo un encabezado que dice justamente eso.

Un Check está escrito para el rol al que se le hace. El revisor lee y no corre nada, así que probar que un test nuevo puede fallar — romper la línea que cubre y verlo ponerse en rojo — es obligación del desarrollador y vive en el contrato del desarrollador; al revisor se le pregunta si el desarrollador lo dejó anotado al lado del test, que es una lectura que sí puede hacer y citar.

El cuerpo es tuyo desde el momento en que lo tocas. enable solo reemplaza el esbozo que sembró init, o un cuerpo de pack suyo que se quedó una entrega atrás; un cuerpo que editaste se conserva, y el comando te dice cuál dejó en paz. Los overlays son de la herramienta: se reescriben en cada enable, y en cada init que corra con el interruptor prendido, y disable los quita. A knowledge/ no lo toca nada de esto.

Los skills de tu propio proyecto (.claude/skills/*/SKILL.md) también se le nombran al desarrollador, con interruptor o sin él, cada uno con la ruta a su SKILL.md: el harness corre un skill, y tldrx nada más avisa que está ahí. Uno que git no rastrea queda marcado, porque un worktree de story se lleva solo los archivos rastreados.

Cómo entrenar uno

tldrx expert create billing --area money --title "Facturación, prorrateo y reembolsos"
tldrx expert train billing --area money --mode light --print-prompt   # gratis: imprime y se para
tldrx expert train billing --area money --mode light

--mode light lee el código. --mode full escarba en los handoffs de los runs terminados; los expertos de rol solo se entrenan en full, porque su materia es el flujo de trabajo y no una carpeta de código.

Dos cosas hacen que el resultado sea confiable:

• Ningún modelo elige qué leer. Una pasada previa determinista escoge los archivos a partir del mapa de código, del grafo y de una búsqueda acotada por palabras clave — con tope de 40 archivos y 96 KB, y todo lo que rebasa el tope queda listado por nombre como "not read", para que un subagente no pueda describir un archivo que nunca le enseñaron.
• El dominio declarado del experto es un límite duro. Una cita fuera de él no le gana evidencia a ese experto, por muy cierta que sea. Los bullets de ## Domain en expert.md son rutas relativas a un repo, sin prefijo de repo — - `src/Checkout/`, nunca - `api/src/Checkout/` — porque una cita llega como repo:ruta:línea y solo se compara la mitad de la ruta. create escribe esa regla, y el repos: del front matter, en el archivo que crea.

Un experto sin área no se puede entrenar, y por eso --area va arriba: sin ella, expert train se niega y nombra el bloque que hay que agregar a competencies.yml.

tldrx expert recompute vuelve a derivar cada nivel a partir de la evidencia que hay en disco. tldrx expert rescore va un paso más atrás: vuelve a leer los propios archivos de conocimiento y deriva su evidencia otra vez, que es lo que quieres después de un cambio en lo que cuenta como evidencia. Ninguno de los dos lanza nada ni gasta nada. Una fila re-puntuada conserva la fecha en que se leyó su afirmación y lleva una segunda que dice cuándo se puntuó, y el rescore se escribe a sí mismo en el ledger del experto con costo $0 — así un nivel que subió gratis nunca se lee como uno que alguien pagó.

¿De verdad hace falta?

No. Un experto sin entrenar se gana una nota en stderr que nombra su comando de entrenamiento, y nunca bloquea nada ni cambia un código de salida. Entrenar es lo que haces cuando una etapa se la pasa volviendo a deducir lo mismo sobre tu código: el conocimiento entrenado ya viene con sus fuentes, así que la etapa siguiente lo puede reusar tal cual en lugar de pagar por redescubrirlo.

El detalle completo: 4 — Experts.