ultradoc

ultradoc — responde preguntas desde la fuente, no desde la memoria

ultradoc responde preguntas ultraprecisas sobre un proyecto open-source recuperando evidencia fundamentada y razonando sobre ella. El motor determinista (scripts/ultradoc.mjs, Node sin dependencias) realiza la búsqueda e indexación con código; tu trabajo es leer la evidencia recuperada y escribir una respuesta precisa y citada. Cada afirmación debe apuntar a una fuente real. Esto se aplica: ultradoc check falla si alguna cita no se resuelve a la evidencia recuperada.

La regla fundamental: no respondas desde tu propio conocimiento de la biblioteca. Tus datos de entrenamiento están desactualizados y alucinan APIs. Responde solo a partir de la evidencia que ultradoc recupera del repositorio real, issues, PRs, documentación y la web. Si la evidencia no lo cubre, dilo y recupera más — nunca adivines.

El script

Un único paquete consolidado sin dependencias: node scripts/ultradoc.mjs <comando>. No necesita npm install, ni claves API. Ejecuta --help para ver la superficie completa. Comandos clave:

• ask --repo <url|ruta> --q "<pregunta>" [--sources ...] [--package <p>] [--semantic] [--docs-url <u>] Clona (cualquier URL de git, almacenada en caché en /tmp/ultradoc/<slug>), indexa, recupera de todas las fuentes seleccionadas y escribe un dosier de evidencia (EVIDENCE.md, evidence.json, meta.json) en una carpeta de ejecución — almacenada junto al clon en <clon>/.ultradoc/runs/<id> (un hogar estable y fijado por commit reutilizado entre preguntas), a menos que pases --out. Fuentes predeterminadas: code,issues,prs,docs (agrega web,so cuando el repositorio solo no responda; agrega releases,history para preguntas sobre "cuándo se añadió / cambió X", y discussions para preguntas de la comunidad — necesita la CLI gh). En un monorepo, --package <nombre|directorio> limita la recuperación de código/documentación a un paquete del espacio de trabajo.
• code|issues|prs|docs|releases|history|discussions|so --repo <...> --q "..." — profundiza en UNA fuente, imprime la evidencia en la salida estándar (sin dosier). Úsalos para expandir un área delgada. history ejecuta git pickaxe (log -S/-G) en el clon — la primera llamada en un repositorio remoto obtiene el historial completo una vez.
• web --repo <...> [--q "..."] [--url <u,...>] — descubrimiento web sin claves (SearXNG → DuckDuckGo → tu WebSearch) + obtención/extracción. Pasa --url para fundamentar una página específica que encontraste con tu propio WebSearch.
• overview --repo <...> [--refresh] — genera (una vez) un resumen markdown en caché del repositorio: qué es, sus paquetes del espacio de trabajo, estructura, API pública y mapa de documentación. Se almacena en caché junto al clon y se reutiliza mientras el commit no cambie — léelo para orientarte en varias preguntas sin reindexar. Es un mapa de navegación, NO evidencia citable.
• doc --repo <...> [--package <p>] [--sources ...] — prepara un documento de referencia fundamentado: un esquema de secciones determinista (resumen, instalación, API pública/por paquete, configuración, arquitectura), un dosier recuperado por sección fusionado en un único evidence.json, y una lista de trabajo DOC.todo.md. Tú escribes la prosa citada en DOC.md; check la valida como una respuesta. Se almacena en <clon>/.ultradoc/doc/. Ver "Generar documentación" más abajo.
• check --run <directorio-dosier> — valida las citas de ANSWER.md (o de un DOC.md de una ejecución de doc) contra el evidence.json del dosier. Sale con código distinto de cero ⇒ no fundamentado. --answer <archivo> valida un archivo específico.
• index --repo <...> — construye/imprime el índice estructural (depuración / inspección); lista los paquetes del espacio de trabajo descubiertos en un monorepo.
• semantic up|down|status — backend vectorial local opcional (ver más abajo).

Flujo de trabajo

Eres responsable de esta tarea de principio a fin: devuelve una respuesta fundamentada y citada, y nunca entregues un dosier recuperado a medias. Pero el trabajo de recuperación y verificación consiste en un conjunto de llamadas independientes y casi gratuitas — paralelízalas cuando tu entorno lo permita (agrupa las perforaciones independientes en un mensaje; distribuye a subagentes o un flujo de trabajo si está disponible) y hazlo en línea en caso contrario. Itera en rondas hasta que la evidencia esté completa; no devuelvas nada hasta que lo esté. Ver references/orchestration.md.

1. Resuelve el objetivo. Identifica el proyecto y la pregunta precisa. Si solo tienes un nombre, encuentra la URL canónica del repositorio (usa tu WebSearch, o pregúntale al usuario si es ambiguo). Anota cualquier versión/rama que le interese al usuario (--ref).

   ¿Varias preguntas sobre el mismo repositorio? Ejecuta overview --repo <url> una vez y lee el OVERVIEW.md almacenado en caché que imprime: mapea el repositorio (paquetes, estructura, API pública, documentación) para que las preguntas siguientes reutilicen el mismo clon + índice en lugar de reorientarte desde cero. Nunca lo cites — es navegación, no evidencia.

   ¿Monorepo? Si ask/index/overview informa paquetes del espacio de trabajo (p.ej., socialgouv/code-du-travail-numerique → @cdt/frontend, @socialgouv/modeles-social, …), elige el paquete cuyo nombre/directorio coincida con el subsistema sobre el que trata la pregunta y añade --package <nombre|directorio> para que la recuperación no se ahogue en los otros paquetes. Si ningún nombre de paquete coincide obviamente, ejecuta primero un ask sin alcance, observa en qué paquete se agrupan los principales resultados, luego vuelve a ejecutar con alcance. Un nombre de paquete desconocido falla ruidosamente y lista los que existen.

2. Recupera. Primero, piensa como un desarrollador y deriva 2–3 variantes de consulta para la pregunta — el motor busca literalmente, por lo que la redacción importa:

   • la redacción en lenguaje natural ("retry backoff" / "retroceso de reintento"),
   • las formas de identificadores que probablemente use el código base (retryBackoff, retry_backoff, MAX_RETRIES),
   • el mensaje de error literal, el nombre de opción o bandera si el usuario citó uno.

   ¿Pregunta de múltiples partes? Divídela en subpreguntas ahora — cada una necesita su propia evidencia o un "desconocido" explícito al final. Haz un seguimiento de la cobertura por subpregunta.

   El motor ya maneja plurales y acentos ("retries"/"retry", "délai"/"delai"), divide los identificadores en subtokens, y prioriza archivos nombrados con una palabra clave — así que gasta tus variantes en sinónimos e identificadores ("heartbeat"/"latido" vs ping, "pool" vs connectionLimit), no en inflexiones de la misma palabra. Y sabe cuándo la búsqueda léxica será delgada: necesita palabras que aparezcan literalmente en el repositorio. Para preguntas conceptuales o de "por qué se diseñó así", comienza con docs, discussions, web (o --semantic) en lugar de esperar que code lleve la respuesta.

   Ejecuta ask con la mejor variante y las fuentes que correspondan:

   node scripts/ultradoc.mjs ask --repo <url> --q "<pregunta precisa>" --sources code,issues,prs,docs
   

   ultradoc descubre automáticamente la URL de documentación oficial del proyecto a partir de su propio README/manifiestos (y prioriza el árbol docs/ canónico en el repositorio), luego fundamenta contra ella — pasa --docs-url <url> solo para sobrescribir. Añade web,so cuando la pregunta es conceptual o el repositorio es escaso; añade releases,history cuando se trata de cuándo/porqué/qué versión cambió algo. El comando imprime la ruta del dosier. Luego trata las variantes restantes × fuentes de perforación como una expansión — emite esas perforaciones independientes como llamadas paralelas en un mensaje (o un subagente por celda). Ver references/orchestration.md.

3. Lee el dosier. Abre EVIDENCE.md en la carpeta de ejecución. Cada elemento tiene un id ([E1], [E2], …), una referencia de procedencia ref y un fragmento. Esta es tu evidencia — lee el texto real del código/issue/PR/documentación.

4. Perfora en las carencias. Una subpregunta es delgada cuando tiene menos de ~2 elementos relevantes, o ningún elemento contiene realmente el símbolo/comportamiento preguntado. No esperes a que un dosier parezca delgado para perforar las variantes — ejecuta las perforaciones de variantes en paralelo desde el principio (las perforaciones son casi gratuitas: el clon y el índice están en caché). Expándelas a través de las fuentes:

   • code --repo <...> --q "<símbolo o comportamiento>" para extraer más regiones de código.
   • issues/prs para leer discusiones relacionadas y cambios en curso.
   • releases (registro de cambios + notas de versión) y history (git pickaxe) cuando la pregunta es sobre cuándo/porqué/qué versión cambió algo.
   • discussions para preguntas de la comunidad y hilos de diseño (necesita la CLI gh).
   • web (o tu WebSearch → web --url <u>) para referencias externas. Sigue references/retrieval-playbook.md para saber cómo iterar y references/orchestration.md para saber cómo ejecutar las perforaciones en paralelo.

   Triaje antes de escribir. La recuperación está orientada a la exhaustividad, por lo que el dosier contendrá elementos fuera de tema que solo comparten palabras clave. La prueba: un elemento es relevante para la pregunta solo si su fragmento nombra el símbolo/comportamiento preguntado o describe el mismo mecanismo — compartir una palabra clave no es suficiente. Enumera qué ids de evidencia pasan esa prueba e ignora el resto — un elemento fuera de tema no debe citarse solo porque existe. Si después del triaje menos de ~2 elementos respaldan la afirmación principal, vuelve y recupera más.

   Vuelve a consultar en lugar de releer. Si los 3 elementos principales de código están fuera de tema, no sigas leyendo hacia abajo en la lista — vuelve a ejecutar code --q con la siguiente variante con forma de identificador del paso 2. Dos dosieres fuera de tema seguidos significan que la redacción es incorrecta, no que al repositorio le falte la respuesta.

   Repite hasta agotar. Perfora en rondas (límite ~3). Detente cuando una ronda no descubra nueva evidencia relevante, o cuando cada subpregunta tenga ≥2 elementos de respaldo — luego haz el triaje y escribe. Una subpregunta aún sin respaldo después del límite es un desconocido explícito, nunca se completa desde la memoria.

5. Escribe la respuesta. Crea ANSWER.md en la misma carpeta de ejecución. Sé preciso y conciso. Cita cada afirmación factual con el id de evidencia en el que se basa, p.ej., Los reintentos usan retroceso exponencial con jitter [E1], y el PR #79 está reescribiendo esto [E7]. Ver references/citation-format.md. Fija la respuesta al commit que se muestra en meta.json cuando la versión importe. Cubre cada subpregunta del paso 2; marca cualquier cosa que la evidencia no resuelva como un desconocido explícito — no lo completes desde la memoria.

6. Valida (dos capas).

   • Estructural: node scripts/ultradoc.mjs check --run <directorio-dosier>. Falla en cualquier cita que no se resuelva a evidencia, o en una respuesta sin citas. Corrige y vuelve a ejecutar hasta que pase.
   • Semántica (verificación adversarial de respaldo): node scripts/ultradoc.mjs verify --run <directorio-dosier> escribe una lista de trabajo afirmación↔evidencia (VERIFY.todo.json + VERIFY.md). Juzga cada par como un escéptico: asume por defecto unsupported/refuted a menos que el fragmento citado respalde literalmente la afirmación, estableciendo verdict a supported · partial · refuted · unsupported (+ una nota breve). Ejecuta un escéptico por par — distribuye a subagentes cuando esté disponible (cada uno devuelve su veredicto), de lo contrario adjudica cada par en línea — y recopila cada veredicto en un único verdicts.json (ver references/orchestration.md), luego:

     node scripts/ultradoc.mjs verify --apply verdicts.json --run <directorio-dosier>
     node scripts/ultradoc.mjs check  --semantic --run <directorio-dosier>
     

     Esto falla en citas colgantes/sin fuente (estructural) y en cualquier afirmación refutada o no respaldada — cerrando la brecha donde una cita se resuelve pero en realidad no respalda la afirmación. Corrige la afirmación (vuelve a citar, debilita, elimina o recupera un elemento mejor) y vuelve a verificar hasta que pase. También haz una autoevaluación contra references/answer-rubric.md para completitud/actualidad/ desconocidos.

7. Presenta. Dale al usuario la respuesta fundamentada con sus citas y enlaces (archivo:línea, números de issue/PR, URLs de doc/SO/web de la evidencia), y el commit contra el que se verificó.

Generar documentación

Cuando el usuario quiera un documento de todo el proyecto (o de todo el paquete) en lugar de una respuesta, usa doc — es el mismo bucle fundamentado, expandido sobre un esquema de secciones:

1. Preparación. node scripts/ultradoc.mjs doc --repo <url> [--package <p>]. El motor construye un esquema determinista (resumen, instalación/uso, API pública o una sección por paquete del espacio de trabajo, configuración, arquitectura), recupera un dosier por sección, los fusiona en un único evidence.json con ids globales [E#], y escribe DOC.todo.md (la lista de trabajo por sección) + DOC.plan.json. Añade --sources code,docs,issues,prs para fundamentar secciones en más que código + documentación. Se almacena en <clon>/.ultradoc/doc/.
2. Escribe cada sección. Lee DOC.todo.md y EVIDENCE.md, luego escribe DOC.md en la carpeta de ejecución: una sección por entrada del esquema, cada afirmación citada [E#]. Una sección cuya evidencia es delgada es una unidad de expansión — perfórala (code|docs|issues …) o marca la carencia como un desconocido explícito; nunca escribas desde la memoria. El trabajo por sección se paraleliza — ver references/orchestration.md.
3. Valida y presenta. node scripts/ultradoc.mjs check --run <directorio-doc> (y verify + check --semantic para la compuerta de respaldo, exactamente como en el paso 6 — ambos detectan automáticamente DOC.md). Corrige hasta que esté fundamentado, luego presenta DOC.md fijado a su commit.

Modo semántico opcional (totalmente local, sin clave API)

La búsqueda determinista de nivel 1 (ripgrep + índice de símbolos) es la predeterminada y no necesita nada. Para preguntas más difusas y conceptuales puedes habilitar la búsqueda semántica local:

node scripts/ultradoc.mjs semantic up      # docker compose: Qdrant + Ollama (+ SearXNG)
node scripts/ultradoc.mjs ask --repo <url> --q "..." --semantic

Todo se ejecuta en contenedores Docker locales — sin clave, ningún dato sale de la máquina. Si la pila no está levantada, --semantic registra un aviso y vuelve al nivel 1. Ver references/semantic-setup.md.

Referencias

• references/orchestration.md — cómo paralelizar perforaciones de recuperación y verificación entre llamadas/subagentes, con los contratos de devolución + ensamblaje de veredictos y el respaldo secuencial.
• references/retrieval-playbook.md — cómo elegir fuentes e iterar hacia una respuesta completa.
• references/citation-format.md — la gramática de citas que check aplica.
• references/answer-rubric.md — la autoevaluación semántica antes de presentar.
• references/provider-apis.md — cómo se obtienen issues/PRs por alojamiento, sin claves.