Un experto en cualquier repo
que cita sus fuentes.

Fuentes heterogéneas sin integrar. Un repo tiene documentación, código fuente e issues activos. Un sistema RAG que indexa solo una de ellas responde peor que un developer con grep bien entrenado.

Sin routing de fuentes. Preguntar "¿dónde está el bug del issue #42?" no es lo mismo que "¿qué hace la función parse_config?". Sin routing inteligente, el sistema mezcla fuentes irrelevantes con las pertinentes.

Respuestas sin trazabilidad. Un LLM que responde sin citar fuentes da la misma confianza que uno que alucina. Si no puedes verificar la respuesta, no sirve para trabajo real.

Instancias hardcodeadas. La mayoría de sistemas RAG son one-repo. Cambiar de repositorio implica reescribir código. Un sistema configurable desde config escala sin rozamiento.

El modelo de embeddings era solo inglés.
Síntoma: "¿Qué proyectos ha construido Jorge?" devolvía plantillas de prompts de otros repos.
Diagnóstico: mismo índice, misma fusión, cambiando solo el idioma de la pregunta — en inglés devolvía 6/6 fragmentos de carrera correctos; en español, 6/6 irrelevantes. El corpus está en inglés y el chat se usa en español.
Arreglo: cambio a multilingual-e5-small, multilingüe y de la misma dimensión (384), con los prefijos query:/passage: que ese modelo espera. Solo hubo que recalcular los vectores, no migrar el esquema. Recuperación de carrera: 0.6 → 1.0.

La fusión era una cuota disfrazada de ranking.
Síntoma: toda pregunta devolvía exactamente 2 fragmentos de cada colección.
Diagnóstico: RRF puntúa por el puesto dentro de cada colección, así que todos los primeros empataban y la mezcla era un round-robin. Una pregunta sobre la carrera gastaba cuatro de seis huecos en código de repositorios.
Arreglo: reparto proporcional de huecos según lo bien que encaja cada colección, medido contra el rango de puntuaciones de esa consulta — necesario porque las similitudes del nuevo modelo se agrupan en una banda estrecha (~0.78–0.88) donde los cocientes en bruto no dicen nada. Una colección sin nada relevante ahora no ocupa ningún hueco.

El 55% de los fragmentos de carrera se truncaban sin avisar.
Síntoma: datos que existían en el documento no aparecían nunca.
Diagnóstico: 12 de 22 secciones superaban la ventana del modelo (la mayor, ~4×), y el truncado es silencioso: se indexaba solo hasta el corte.
Arreglo: las secciones largas se parten por frases — nunca a mitad de una — repitiendo el encabezado en cada trozo para que el embedding siga en tema y la cita conserve contexto. 22 → 56 fragmentos, el mayor de 4.952 a 899 caracteres, ninguno por encima del límite.

El 40% del corpus era ruido interno.
Síntoma: una pregunta sobre proyectos de ML respondía citando una oferta de empleo ficticia.
Diagnóstico: 1.003 fragmentos de ficheros de tareas y 161 de plantillas de prompts de otros repos, que competían con la documentación real.
Arreglo: excluidos del índice. El patrón de exclusión además no funcionaba en la raíz del repositorio — fnmatch deja que * cruce /, así que **/tasks/** exigía una barra antes de tasks — y se corrigió en el comparador, con tests. Docs: 2.885 → 1.691 fragmentos.

Y una trampa de medición, que casi me hace "arreglar" lo que no estaba roto.
Síntoma: tras ampliar el contexto del generador, la fidelidad cayó de 0.7 a 0.1.
Diagnóstico: el juez recupera su propia evidencia y seguía haciéndolo con 5 fragmentos recortados a 700 caracteres, mientras el generador ya usaba 12 de 2.400. Marcaba como no fundamentadas respuestas correctas porque el texto que las sostenía estaba fuera de su vista.
Arreglo: el juez ve ahora la misma amplitud que el generador. Documentado como arreglo de medición y no de calidad, para que nadie lea esa subida como una mejora del sistema.