# skill-gibbs-hyperresearch-2026-08-03

## Veille

Entrada de **Skill** (no es un artículo): **hyperresearch**, de **Jordan Gibbs**, es un **arnés de investigación profunda** (deep research harness) que convierte Claude Code en un agente de investigación documental, distribuido como paquete PyPI (MIT, Python 3.11-3.13) que instala **20 skills de Claude Code** + una CLI + un servidor MCP + una interfaz web local. Observado el **3 de agosto de 2026**: 1568 estrellas, 170 forks, repositorio creado el 9 de abril de 2026, último push el 1 de agosto. **El núcleo es un pipeline de 16 pasos adaptativo por nivel** (`light` ~30-40 min → `full` ~1,5-2,5 h → `dissertation` 4-8 h y 25.000-80.000 palabras repartidas en 300-450 fuentes), que toma un prompt y devuelve un informe **auditado de forma adversarial** con procedencia completa. **La decisión de arquitectura central — y la más instructiva — está documentada junto con su modo de fallo**: la skill de entrada es un **router ligero** que no contiene ningún procedimiento en absoluto, y cada paso vive en su propia skill, cargada **de forma nueva en el momento en que se invoca** — porque la versión anterior era *« one 1200-line skill that got compacted away by the time Layer 4 needed its triple-draft procedure. The orchestrator forgot the procedure, wrote a single draft, and produced a flat-scoring report. »* **Dos principios estructurales**: *« Patch, never regenerate »* — tras la síntesis, solo son posibles retoques quirúrgicos vía `Edit`, ya que el parcheador y el auditor de pulido están **bloqueados a nivel de allowlist de Claude Code a las herramientas `[Read, Edit]`**, de modo que *« physically cannot Write a new draft »*; y *« canonical research query is gospel »* — el prompt textual se persiste una sola vez en `query.md` y es releído por cada paso y cada subagente. **Dieciséis subagentes** con rol y modelo configurables (fetchers y cite-checker en Sonnet, críticos/sintetizador/parcheador en Opus). **El vault** es un almacén markdown persistente indexado en SQLite — *« Markdown is truth, SQLite is cache »* — con un ciclo de vida de nota (`draft → review → evergreen`, `stale → deprecated → archive`), procedencia trazable, una puntuación de calidad compuesta (tipo de fuente, autoridad de citación vía OpenAlex/Semantic Scholar **con indicadores de retractación**, PageRank interno) y una **auditoría de independencia** que agrupa las copias sindicadas — *« five reprints of one press release argue with the weight of one source »*. **Tres barreras mecánicas antes de publicar**: integridad de citación (cualquier pasaje citado debe existir **textualmente** en una nota del vault), un escaneo de retractaciones actualizado en cada DOI citado, y verificación del enlace cita-frase por un LLM escéptico. ⚠️ **Reserva importante a señalar**: la afirmación central — *« currently leads the DeepResearch-Bench RACE leaderboard »* — queda contradicha por su propia nota al pie, *« forward-looking projection from a stratified pilot… Third party validation is pending »*. Una **proyección** no es una clasificación, y sin embargo el gráfico la sitúa por delante de Gemini y de OpenAI Deep Research de todos modos.

## Titre Article

hyperresearch — « The Most Powerful Deep Research Harness » / « Agent-driven research knowledge base. Agents collect, search, and synthesize web research into a persistent, searchable wiki. »

## Date

2026-08-03

## URL

https://github.com/jordan-gibbs/hyperresearch

## Keywords

skill, investigación profunda, arnés de investigación, Claude Code, pipeline de 16 pasos, tiers, light, full, dissertation, gear, perfil de escala, router ligero, carga diferida, compactación de contexto, desalojo de procedimiento, skill por paso, parchear nunca regenerar, retoque quirúrgico, bloqueo de herramientas, tool-locked, allowlist, Read Edit, consulta canónica, prompt textual, gospel, subagentes, fetcher, loci-analyst, depth-investigator, draft-orchestrator, sintetizador, críticos adversariales, crítico dialéctico, cite-checker, parcheador, auditor de pulido, vault, markdown como fuente de verdad, SQLite caché, índice reconstruible, ciclo de vida de nota, evergreen, deprecated, procedencia, suggested-by, puntuación de calidad, PageRank, OpenAlex, Semantic Scholar, retractación, auditoría de independencia, sindicación, quote-integrity, numeric-consistency, ship gate, lint, inyección de prompts, untrusted-source, texto web como datos, SSRF, Unpaywall, Europe PMC, acceso abierto, nota rescatada, nothing_from_source, versión de registro, escalado a navegador, Claude-in-Chrome, CAPTCHA nunca resuelto, presupuesto de ejecución, reanudación de ejecución, MCP, DeepResearch-Bench, proyección no validada, Jordan Gibbs

## Authors

**Jordan Gibbs** — auteur et mainteneur du dépôt `jordan-gibbs/hyperresearch`. Le projet est distribué sous **licence MIT** et publié sur **PyPI** (`pip install hyperresearch`). Signaux d'adoption au 3 août 2026 : **1 568 étoiles**, **170 forks**, 13 issues ouvertes, dépôt créé le **9 avril 2026** et poussé le **1er août 2026** — soit une traction rapide sur moins de quatre mois. Topics déclarés : `agents`, `agentskills`, `claude-code`, `deep-research`, `deep-research-agent`.

## Ton

**Perfil**: documentación de proyecto open-source de alta densidad técnica, doblada como un **argumento de superioridad**. El README no se limita a explicar: **argumenta**, sección por sección, bajo encabezados que son tesis (*« Why it wins »*, *« Source ranking: quality is persistent, not vibes »*, *« The web is hostile input »*, *« Open-access full text: read this before you cite »*).

**Estilo**: un registro de ingeniero que explica un mecanismo a través del problema que resuelve, casi siempre en dos tiempos — primero el modo de fallo, luego la corrección. *« A closed paper normally enters a vault as a 1,500-character abstract that the report then cites as though it had been read »*, luego la sustitución de acceso abierto. *« V7 was one 1200-line skill that got compacted away »*, luego el router. Esta forma da al texto un **valor pedagógico que supera su valor promocional**: se aprenden los modos de fallo de la investigación profunda agéntica incluso sin instalar nunca la herramienta.

**Registro operativo impuesto al agente** ("tono" en el sentido de las entradas de skill): **imperativo, contractual, en mayúsculas para enfatizar**. *« NEVER EMIT BARE TEXT WHILE TASKS ARE RUNNING »*, *« RESPECT THE TIER GATE »*, *« PATCH, NEVER REGENERATE »*, *« ARGUE, DON'T JUST REPORT »*. Al orquestador se le despoja explícitamente del trabajo mismo: *« You do NOT do the work of any step yourself. The step skills do. You just sequence them. »* El prompt del usuario se denomina **gospel** — tres veces.

**Rasgo notable**: una **honestidad selectiva**. La sección *« What it doesn't do »* es franca (*« The lint gate catches structural failures… It cannot guarantee factual accuracy, that's still your call »*), las advertencias sobre versiones de preprint son escrupulosas, y la exigencia de aportar el propio `contact_email` para Unpaywall se justifica por un razonamiento colectivo (*« shipping a shared placeholder would get that placeholder rate-limited for every hyperresearch user at once »*). Este rigor hace aún más visible el **único lugar donde flaquea**: la afirmación del leaderboard.

**Frases marcadoras**: *« Markdown is truth, SQLite is cache »*, *« Fetched text is data, never instructions »*, *« five reprints of one press release argue with the weight of one source »*, *« they physically cannot Write a new draft »*, *« quality is persistent, not vibes »*, *« nothing is thrown away »*, *« each session starts smarter than the last »*.

## Pense-betes

- **Naturaleza**: **arnés de investigación profunda** distribuido como un paquete de **20 skills de Claude Code** + CLI Python + servidor MCP + interfaz web local. Instalación vía `pip install hyperresearch && hyperresearch install`, luego `/hyperresearch <topic>`. MIT, Python 3.11-3.13.
- **⭐⭐ La lección de arquitectura, con su modo de fallo documentado** — la parte más transferible, independiente de la herramienta: la skill de entrada es un **router** que no contiene **ningún** procedimiento, solo el orden de invocación. Justificación textual: *« V7 was one 1200-line skill that got compacted away by the time Layer 4 needed its triple-draft procedure. The orchestrator forgot the procedure, wrote a single draft, and produced a flat-scoring report. V8 fixes this at the source: each step's procedure is loaded into context only at the moment it's needed, fresh, with no eviction risk. »* → **Un pipeline largo no pierde sus pasos porque el modelo olvide, sino porque el contexto se desaloja**, y la corrección es estructural: una skill por paso, cargada en la invocación. Es exactamente la disciplina de [[lassiege-usine-logicielle-heure-ia-2026-07-28]] ("el contexto permanente lleva el índice, no el contenido") **descubierta de forma independiente en otro terreno**. Una convergencia digna de mención.
- **⭐ El bloqueo de herramientas como garantía física**: el parcheador y el auditor de pulido están *« tool-locked to `[Read, Edit]` at the Claude Code allowlist level so they physically cannot Write a new draft »*, con topes por retoque que hacen *que "reescribir sin más" sea mecánicamente imposible*. → **No se le dice al agente que no reescriba — se le retira la herramienta de escritura.** Misma familia que *« a hook or a test is enforced every time »* ([[lassiege-usine-logicielle-heure-ia-2026-07-28]]) y el anillo de restricciones de [[sfeir-code-review-anneau-contraintes-2026-07-30]]: **la imposibilidad mecánica vence a la instrucción.** Corolario operativo: un hallazgo de crítica que no encaja en un pequeño retoque **escala a problema estructural** en lugar de disparar una reescritura.
- **Los dieciséis pasos, en tres bloques** (la estructura importa más que el detalle): **encuadre** (1 descomposición + matriz de cobertura + clasificación por nivel, 1.5 partición en capítulos) → **corpus y análisis** (2 barrido amplio, 3 grafo de contradicciones, 4 análisis de loci, 5 investigaciones de profundidad en paralelo, 6 reconciliación entre loci, 7 tensiones entre fuentes, 8 crítica del corpus "¿qué fuente refutaría esto?" + relleno de vacíos dirigido, 9 síntesis de evidencia) → **redacción y auditoría** (10 triple borrador por ángulo, 11 síntesis, 12 cuatro críticas adversariales en paralelo, 13 relleno de vacíos post-crítica, 14 parcheador quirúrgico, 14.5 verificación de citas, 15 pulido, 16 auditoría de legibilidad).
- **Tres palancas de escala que no deben confundirse** — una distinción limpia y reutilizable: los **tiers** enrutan según la consulta y deciden **qué pasos se ejecutan**; los **gears** (perfiles de escala) deciden **en qué medida** — objetivos de fuentes, presupuestos de profundidad, longitud — y *« survive reinstalls »*, aplicándose en la siguiente ejecución, **nunca a mitad de ejecución**; las **levers** (`register`, `domain_notes`, `inference_depth`) deciden **con qué voz** sale el resultado — `teach` / `survey` / `analyze` / `advocate`. ⭐ Detalle fino: las levers aterrizan en **shims inyectados en los prompts de los subagentes**, *« so the critics move with the register instead of undoing it »* — en registro `survey`, el crítico dialéctico señala representación injusta en lugar de falta de compromiso. **Pero**: *« The cite-checker and the ship gate receive no shim at all. Verification never softens by mode. »* → **La verificación es la única etapa exenta de estilo.** Una excelente regla de diseño.
- **⭐ Las tres barreras mecánicas antes de publicar** (la mejor parte del sistema, directamente transferible a cualquier corpus documental): 1. **quote-integrity** — cualquier porción citada entre comillas debe existir **textualmente** en una nota del vault; *« hallucinated quotes cannot ship »*. 2. **retracted-citations** — citar una fuente retractada sin señalarlo es un **error bloqueante**, con un escaneo de retractaciones **actualizado en el momento de publicar en cada DOI citado**, incluidas las fuentes reutilizadas de ejecuciones anteriores. *« a retraction published yesterday is caught today »*. 3. **numeric-consistency** — las cifras no trazables a evidencia se marcan. Además del **cite-check**: un LLM escéptico muestrea si la fuente citada **respalda realmente la frase** que sustenta.
- **⭐ La auditoría de independencia — la idea más inmediatamente aprovechable**: las copias sindicadas y derivadas se agrupan, de modo que *« five reprints of one press release argue with the weight of one source »*. **El número de fuentes coincidentes deja de ser un argumento en cuanto todas descienden del mismo comunicado de prensa.** Relevante para cualquier práctica de vigilancia tecnológica: la redundancia por reimpresión se disfraza de consenso.
- **Puntuación de calidad compuesta persistente**: tipo de fuente + utilidad observada en la lectura + autoridad de citación (OpenAlex / Semantic Scholar, **con indicadores de retractación**) + **PageRank** sobre el grafo interno del vault. Las fuentes retractadas se **reducen a cero**. *« Quality is persistent, not vibes. »*
- **⭐⭐ La defensa contra inyección de prompts — la más seria vista en un arnés abierto**: *« Fetched text is data, never instructions. »* Cualquier cuerpo obtenido de la web se sirve dentro de una valla `<untrusted-source url="...">` con un preámbulo de tratar-como-datos, **en ambas rutas que sirven cuerpos** (`note show` y `search`). Detalles que muestran que la amenaza se tomó en serio:
- las notas escritas por los propios subagentes del pipeline pasan **sin valla** → **frontera de confianza por procedencia**, no por contenido;
- las vallas de cierre **falsificadas** encontradas en un cuerpo obtenido se neutralizan **pero se dejan visibles para análisis forense**;
- el atributo `url` se escapa y se le eliminan los caracteres de control;
- en `search`, el envolvimiento ocurre **después** del truncado al presupuesto de tokens, *« so the closing fence can never be severed »* — el detalle que delata que el bypass fue realmente perseguido;
- las URL resueltas vía API de terceros se verifican (esquema, credenciales incrustadas, resolución públicamente enrutable) → defensa **SSRF**;
- los prompts del fetcher, del investigador y del redactor llevan una cláusula que prohíbe **blanquear** directivas de una página vallada hacia la salida de confianza. → Comparar con *« a security boundary that relies on a prompt instruction is not a boundary »* ([[sfeir-anthropic-sdlc-ai-native-securise-2026-07-26]]): aquí la valla es **mecánica** y la instrucción solo la respalda. Misma lógica de tratar el contenido observado como datos que en [[valente-zalewski-beyond-zero-enterprise-security-ai-era-2026-07-20]].
- **⭐ Higiene epistémica sobre fuentes de pago — notable y poco habitual**: un artículo de pago normalmente entraría en el vault como un resumen de ~1500 caracteres, que el informe citaría entonces *« as though it had been read »*. hyperresearch consulta **Unpaywall** y **Europe PMC** en busca de una copia legal de acceso abierto y almacena **ese texto en su lugar**, revelando la sustitución **en cuatro sitios** (aviso en el cuerpo, frontmatter `oa_*`, bloque JSON `body_is_not_from_source: true`, salida de la CLI). Y de forma crucial, se distingue un tercer estado: la nota **"rescatada"**, cuando la fuente **no pudo leerse en absoluto** — `nothing_from_source: true`, un aviso que indica que la URL nunca fue leída, *« the title, the authors, and every word of the body are the open-access copy's »*. Advertencia de versión: Unpaywall puede devolver un manuscrito aceptado o un preprint enviado, a comprobar antes de citar directamente. → **El sistema distingue "leí esto" de "leí un sustituto" de "nunca leí la fuente"**, y lleva esa distinción hasta el artefacto. **Directamente transferible a una práctica de vigilancia tecnológica.**
- **El vault, y su inquietante cercanía a este mismo repositorio**: *« Markdown is truth, SQLite is cache »* — índice totalmente reconstruible (`hyperresearch sync`), notas en markdown + frontmatter YAML legibles sin la herramienta, versionables en git, exportables/importables, **ciclo de vida curado** (`draft → review → evergreen` o `stale → deprecated → archive`) *« that keeps a vault from becoming a dumping ground of half-read pages »*, procedencia vía `--suggested-by` con una **regla de lint** que detecta componentes desconectados, hubs, backlinks, wikilinks. ⭐ **Esta es la arquitectura de este mismo corpus de vigilancia tecnológica, descubierta de forma independiente**: fuente markdown, índice generado como caché, barrera de lint, doctor, wikilinks. Lo que hyperresearch tiene de más y este corpus no tiene: **puntuación de calidad por fuente, auditoría de independencia, escaneo de retractaciones, búsqueda semántica opcional, estado de ciclo de vida explícito**. Una vía de inspiración seria para `scripts/`.
- **Reanudación y presupuesto**: cada ejecución tiene un espacio aislado (`research/runs/<tag>/`) y un **manifiesto** que sirve de *« durable memory »* — una ejecución interrumpida se reanuda exactamente en el paso caído (`run resume`). `run init --budget 50` **bloquea** la ejecución en cuanto se cruza el tope *« rather than letting it quietly balloon »*. Las ejecuciones concurrentes no colisionan.
- **⚠️⚠️ La reserva a señalar sistemáticamente — la afirmación del benchmark**: el README indica de entrada que la herramienta *« currently leads the DeepResearch-Bench RACE leaderboard (benchmarked internally) »*, gráfico incluido, situándola por delante de Grep Deep Research, Cellcog Max, nvidia-aiq, **Gemini Deep Research** y **OpenAI Deep Research**. La nota bajo el gráfico dice otra cosa: *« Forward-looking projection from a stratified pilot against the DeepResearch-Bench leaderboard snapshot. Third party validation is pending. »* → **Una proyección prospectiva, autoadministrada, a partir de un piloto estratificado, sin validación por terceros, no es una clasificación.** Las dos afirmaciones no son compatibles, y es el único lugar del repositorio donde se relaja el rigor mostrado en todo lo demás. **Nunca citar la clasificación; citar el método.**
- **⚠️ Otras limitaciones, algunas reconocidas por el autor**:
- **Dependencia de Anthropic**: *« It runs on Anthropic models via the subagent roster »* — Opus para los críticos, el sintetizador y el parcheador, Sonnet para los fetchers. Se invita explícitamente a un port a Codex, pero no está hecho (*« If anyone wants to port this to Codex, put up a PR! »*).
- **Coste real no cuantificado en euros**: `premier` apunta a 100-130 fuentes solo de escaneo y ~3-5 h; `dissertation` apunta a 300-450 fuentes y 4-8 h. El presupuesto se limita en "gasto equivalente de API", no en coste observado.
- **La limitación honesta, digna de cita**: *« The lint gate catches **structural** failures… It cannot guarantee **factual accuracy**, that's still your call. »* → **Verificación estructural ≠ exactitud factual.** Todo el sistema garantiza que una cita existe, no que sea verdadera.
- **Un límite firme y bienvenido**: *« CAPTCHAs, 2FA, and logins are never solved automatically »* — se escalan y se devuelven al humano.
- **Superficie de dependencias**: 20 skills + 16 subagentes + una CLI que gobierna un navegador autenticado, sobre un repositorio de menos de cuatro meses. La advertencia de [[lassiege-usine-logicielle-heure-ia-2026-07-28]] se aplica plenamente (*« any skill, MCP, or code pulled in from outside must be scrutinized »*).
- **Meta / a enlazar**: la instancia más lograda de la ingeniería de arneses de [[osmani-agent-harness-engineering-2026-04-19]]; converge de forma independiente con [[lassiege-usine-logicielle-heure-ia-2026-07-28]] en la carga diferida de contexto y en que lo ejecutable vence a la instrucción; misma doctrina de frontera mecánica que [[sfeir-anthropic-sdlc-ai-native-securise-2026-07-26]] y [[valente-zalewski-beyond-zero-enterprise-security-ai-era-2026-07-20]]; parentesco de forma con las otras entradas de skill del corpus, [[skill-pocock-grill-with-docs-2026-06]] y [[akhouri-adhd-ideation-divergente-parallele-2026-07-20]]; a leer junto con [[agent-skills-anthropic-2025-10-16]], [[shihipar-claude-code-lessons-building-skills-2026-06-03]] y [[vincent-superpowers-agentic-skills-framework-github-2026-04-02]] sobre la mecánica de las skills; la crítica adversarial en paralelo conecta con la pregunta planteada por [[monperrus-end-of-code-review-agents-supersede-2026-06-11]] sobre lo que una revisión automatizada puede sostener.

## RésuméDe400mots

**hyperresearch** (Jordan Gibbs, MIT, PyPI) convierte Claude Code en un agente de investigación profunda. Observado el 3 de agosto de 2026: 1568 estrellas, repositorio creado en abril. La instalación despliega **20 skills**, una CLI, un servidor MCP y una interfaz web local.

**El pipeline** ejecuta 16 pasos adaptativos por nivel: `light` (~30-40 min) para preguntas acotadas, `full` (1,5-2,5 h) para análisis argumentativo con revisión adversarial, `dissertation` (4-8 h, 25.000-80.000 palabras, 300-450 fuentes) bajo petición explícita. Tres palancas distintas: los **tiers** deciden qué pasos se ejecutan, los **gears** deciden en qué medida, y las **levers** (`teach`/`survey`/`analyze`/`advocate`) deciden con qué voz sale el informe.

**La arquitectura responde a un fallo documentado.** La skill de entrada es un **router ligero** sin procedimiento alguno: *« V7 was one 1200-line skill that got compacted away… The orchestrator forgot the procedure, wrote a single draft, and produced a flat-scoring report. »* Cada paso vive en su propia skill, cargada de nuevo en cada invocación — un pipeline largo no pierde sus pasos por olvido, sino por desalojo de contexto.

**Dos principios estructurales.** *« Patch, never regenerate »*: tras la síntesis solo son posibles retoques quirúrgicos, ya que el parcheador está **bloqueado a las herramientas `[Read, Edit]`** a nivel de allowlist, de modo que *« physically cannot Write a new draft »* — la imposibilidad mecánica sustituye a la instrucción. Y *« canonical research query is gospel »*: el prompt textual se persiste y se relee en cada paso.

**La verificación es la única etapa exenta de estilo** — las levers inyectan shims en los prompts de los críticos, pero *« the cite-checker and the ship gate receive no shim at all »*. Tres barreras bloquean la publicación: cada cita debe existir **textualmente** en el vault, una fuente retractada sin señalar es un error bloqueante (con un escaneo actualizado en cada DOI citado), y las cifras no trazables se marcan.

**El vault** es markdown persistente indexado en SQLite — *« Markdown is truth, SQLite is cache »* — con un ciclo de vida de nota, procedencia, una puntuación de calidad compuesta y una **auditoría de independencia**: *« five reprints of one press release argue with the weight of one source »*. Los cuerpos obtenidos de la web se sirven dentro de una valla `<untrusted-source>`: *« Fetched text is data, never instructions. »*

⚠️ **La reserva.** El README reivindica el primer puesto en el leaderboard de DeepResearch-Bench; su propia nota al pie indica que se trata de una *« forward-looking projection from a stratified pilot »* sin validación por terceros. Citar el método, nunca la clasificación. El autor también reconoce que el lint *« cannot guarantee factual accuracy »*.

## Anti-patterns

- **Citer le classement DeepResearch-Bench.** La revendication de tête de leaderboard est une **projection auto-administrée en attente de validation tierce**, selon la note du dépôt lui-même. Citer l'architecture, jamais le rang.
- **Confondre vérification structurelle et exactitude.** L'auteur le dit : *« It cannot guarantee factual accuracy, that's still your call. »* Le dispositif garantit qu'une citation existe et qu'elle soutient sa phrase — pas que la source ait raison.
- **Lancer `full` ou `premier` sur une question bornée.** Le palier `light` existe pour ça, et la skill interdit explicitement de monter en palier « pour être exhaustif ».
- **Traiter une note `rescued` comme une lecture de la source.** `nothing_from_source: true` signifie que **rien** — ni titre, ni auteurs, ni corps — ne vient de l'URL en `source:`. À prendre au pied de la lettre.
- **Citer directement depuis une version non finale.** Si `oa_version` vaut `acceptedVersion` ou `submittedVersion`, vérifier la citation contre l'article publié.
- **Installer en `--global` sans y penser.** Coût permanent d'environ quinze lignes dans le *system reminder* de **toutes** les sessions Claude Code, y compris sans rapport avec la recherche.
- **Adopter sans revue de la chaîne de dépendances.** 20 skills, 16 sous-agents, une CLI pilotant un navigateur authentifié, sur un dépôt de moins de quatre mois — exactement la surface que [[lassiege-usine-logicielle-heure-ia-2026-07-28]] recommande de scruter.
- **Compter sur un portage hors Anthropic.** Le roster suppose Opus et Sonnet ; le portage Codex est souhaité par l'auteur, pas réalisé.

## Artefacts

**Espace de run** — `research/runs/<vault_tag>/` :
- `query.md` — le prompt utilisateur verbatim, référence canonique de tout le pipeline
- `run.json` — le manifeste (transitions d'étapes, dépense, file d'escalades) ; support de la reprise
- `scaffold.md` — document de planification privé, **interdit d'apparition dans le rapport final**
- `prompt-decomposition.json` — items atomiques, matrice de couverture, palier retenu
- `loci.json`, `comparisons.md`, `source-tensions.json`, `evidence-digest.md` — sorties d'analyse intermédiaires
- `temp/orchestrator-notes.md` — journal de raisonnement de l'orchestrateur
- `final_report.md` — le livrable

**Vault** — `research/notes/` : une note markdown par source, frontmatter YAML (dont `oa_url`, `oa_version`, `oa_recovery_kind`, `raw_file`, statut de cycle de vie), PDF bruts en `research/raw/<note-id>.pdf`, index SQLite **reconstructible** par `hyperresearch sync`, pages d'index générées, graphe de liens et de provenance.

**Sorties hors Claude Code** : serveur MCP (treize outils dont `search_notes`, `read_many`, `get_backlinks`, `lint_vault`), UI web locale sur le port 8080 sans dépendance JavaScript, exports JSON et vault filtré.

## Commentaire

**En une phrase** : hyperresearch est un harnais qui traite la recherche documentaire agentique comme une **chaîne de production sous contraintes mécaniques**, où chaque risque connu du deep research par LLM reçoit une parade structurelle plutôt qu'une consigne.

**L'idée centrale** est que les modes d'échec du deep research agentique sont **connus et énumérables**, donc outillables un par un. Le README les nomme et leur oppose chaque fois un mécanisme : le rapport dérive en réécriture ? On retire l'outil d'écriture. Le modèle oublie une étape en cours de route ? On charge la procédure au moment de l'invocation. Une citation est inventée ? Elle doit exister verbatim dans le vault, ou le rapport ne part pas. Cinq sources concordent ? On vérifie qu'elles ne sont pas cinq reprises d'un même communiqué. Une page web s'adresse à l'agent ? Son corps est servi dans une clôture qui le désigne comme donnée. Un article payant n'est lu qu'en abstract ? On va chercher une copie légale et on **déclare** la substitution.

**Les principes** qui structurent l'ensemble se ramènent à trois. **La contrainte bat la consigne** — le verrouillage d'outils, les gates de lint et les clôtures ne dépendent pas de la coopération du modèle. **Le contexte se charge au dernier moment** — le routeur mince existe parce qu'un long contexte se fait évincer, ce qui est un fait d'ingénierie et non un défaut de rédaction du prompt. **La vérification ne se négocie pas** — le style du rapport est paramétrable, la vérification ne l'est pas.

**En résumé** : c'est le dispositif de deep research agentique le plus complètement instrumenté publiquement disponible à ce jour, et sa documentation vaut d'être lue **même sans l'installer**, parce qu'elle constitue un catalogue raisonné des façons dont une recherche menée par agent se trompe. Sa faiblesse est ailleurs : une revendication de performance que ses propres notes de bas de page ne soutiennent pas.

## Déclencheur

**Quand la skill s'active** : sur invocation explicite `/hyperresearch <sujet>` dans Claude Code, après `pip install hyperresearch && hyperresearch install` dans le projet (ou `--global` pour toutes les sessions, au prix d'environ quinze lignes dans le *system reminder* de chaque session).

**Entrées attendues** :
- un **prompt de recherche en langue naturelle**, dont la forme verbale détermine le registre du rapport (« explique-moi X » → `teach` ; « quel est le paysage » → `survey` ; défaut → `analyze` ; « défends la thèse que » → `advocate`) ;
- optionnellement, une demande explicite de palier `dissertation` — jamais choisi automatiquement ;
- optionnellement, un plafond de dépense (`run init --budget`), un gear installé (`profile use premier`), ou des directives explicites de registre qui l'emportent sur l'inférence.

**Ce qui est résolu automatiquement au démarrage** : création du vault si absent, installation des 16 skills d'étapes si absentes, archivage des artefacts d'anciennes versions, frappe d'un `vault_tag` unique, initialisation de l'espace de run.

**Quand ne pas la déclencher** : question factuelle simple à réponse connue (le palier `light` existe mais reste une trentaine de minutes), sujet sans littérature accessible, ou besoin d'une réponse immédiate.

## Fonctionnement

**La boucle de l'orchestrateur** est délibérément pauvre : lire le fichier d'entrée une fois → bootstrapper les entrées canoniques → invoquer `Skill(skill: "hyperresearch-N-...")` dans l'ordre dicté par le palier → entre deux étapes, ne rien faire d'autre que marquer les todos et consigner des notes. L'orchestrateur **ne fait le travail d'aucune étape**.

**Le mécanisme d'échelle**, en trois couches indépendantes :

| Couche | Décide | Quand elle s'applique |
|---|---|---|
| **Palier** (`tier`) | quelles étapes tournent | classé par l'étape 1, par requête |
| **Gear** (profil) | l'ampleur : sources, profondeur, longueur | rendu à l'installation, effectif au run suivant |
| **Levers** | le registre et la profondeur d'inférence | inférés du prompt, surchargeables |

**Le fan-out** repose sur seize sous-agents aux rôles fixes et aux modèles configurables : fetchers (8-12 en parallèle par vague), analystes de sources longues, analystes de loci, investigateurs de profondeur (K en parallèle), trois rédacteurs d'angle, un synthétiseur, **quatre critiques adverses en parallèle** (dialectique, profondeur, largeur, instruction), un patcheur, un vérificateur de citations, un auditeur de polissage, un recommandeur de lisibilité, un fetcher-navigateur.

**La chaîne de contrôle en fin de course** est ce qui distingue le dispositif : les critiques attaquent le brouillon → leurs conclusions ne peuvent être appliquées que par un patcheur **incapable d'écrire un fichier** → les conclusions trop larges pour une retouche remontent comme problèmes structurels → un vérificateur sceptique échantillonne les liaisons citation-phrase → une batterie de vérifications bloque l'expédition (citation verbatim, rétractation, cohérence numérique).

**La boucle longue** est le vault : chaque source lue y demeure, indexée et scorée, et la session suivante y cherche **avant** de récupérer quoi que ce soit du web — *« each session starts smarter than the last »*.

## Lecture commentée du SKILL.md

Le fichier commenté est la skill d'entrée, `src/hyperresearch/skills/hyperresearch.md` (~24 Ko).

**Le frontmatter annonce la nature du fichier — un routeur, pas une procédure** :

```yaml
name: hyperresearch
description: >
  Deep research via the HYPERRESEARCH V8 architecture — a tier-adaptive 16-step
  pipeline (light / full / dissertation) … This entry skill is a ROUTER.
  It does not contain step procedures — it tells you which Skill to invoke
  for each step, in order.
```

*Glose* : la `description` est ce que l'agent lit pour décider de charger la skill ; y écrire en majuscules **ROUTER** et nier explicitement la présence de procédures est un choix de design — l'agent est prévenu qu'il devra invoquer autre chose. On notera les **marqueurs de gabarit** `<< p.time_estimate >>` : le fichier est **rendu à l'installation** depuis le profil d'échelle, ce qui explique que changer de gear « prenne effet au run suivant, jamais en cours de run ».

**La dépossession de l'orchestrateur, énoncée d'emblée** :

> *« You are the orchestrator. Your entire job in this conversation is: 1. Read this file once at the start. 2. Bootstrap canonical inputs… 3. Invoke each step skill in sequence via the `Skill` tool. 4. Between steps, do nothing except mark todos and (optionally) think… You do NOT do the work of any step yourself. »*

*Glose* : la contre-mesure vise la tendance d'un orchestrateur à « aider » en faisant lui-même le travail de l'étape suivante — ce qui contaminerait son contexte et casserait le bénéfice du chargement différé.

**Le passage le plus instructif du dépôt, la justification du design** :

> *« Why this design? Context compaction. V7 was one 1200-line skill that got compacted away by the time Layer 4 needed its triple-draft procedure. The orchestrator forgot the procedure, wrote a single draft, and produced a flat-scoring report. V8 fixes this at the source: each step's procedure is loaded into context **only at the moment it's needed**, fresh, with no eviction risk. »*

*Glose* : un **post-mortem** intégré à la documentation d'architecture. Le symptôme (un seul brouillon au lieu de trois) était silencieux — rien n'échouait, la qualité baissait. C'est le mode d'échec le plus dangereux d'un pipeline long, et la seule parade fiable est de ne pas dépendre de la persistance du contexte.

**Le bootstrap installe la mémoire durable avant toute étape** — sept points numérotés dont trois portent l'essentiel :

> *« Persist the query file. Write the verbatim canonical query to `research/runs/<vault_tag>/query.md` … This file is the **canonical query reference for the entire pipeline**. Every step skill and every subagent reads it by path. »*

> *« The manifest is your durable memory: record every step transition with `hyperresearch run step <vault_tag> <N> --status running|done -j` as you go. »*

> *« Seed the TodoWrite list … The todo list survives context compaction; it's your durable memory of where you are in the chain. »*

*Glose* : **trois mémoires externes redondantes** — le fichier de requête pour *quoi*, le manifeste pour *où j'en suis* de façon persistante et interrogeable, la todo list pour *où j'en suis* dans la fenêtre courante. Toutes trois existent parce que le contexte, lui, ne survit pas. Le choix de nommer la todo list « durable memory » dit tout du problème traité.

**Les quatre règles canoniques, en majuscules** :

> *« 1. NEVER EMIT BARE TEXT WHILE TASKS ARE RUNNING. In non-interactive (`-p`) mode, a text-only response (no tool call) triggers `end_turn` — the process exits and the pipeline dies. »*

*Glose* : une contrainte **du harnais**, pas du modèle — en mode `-p`, une réponse sans appel d'outil termine le processus. La parade recommandée (écrire ses pensées dans `orchestrator-notes.md`) transforme une limite d'exécution en journal de raisonnement. Détail révélateur d'un projet qui tourne vraiment en non-interactif.

> *« 2. PATCH, NEVER REGENERATE. … Both subagents are tool-locked to `[Read, Edit]`. If a critic's finding would require rewriting a whole section, it escalates to you as a structural issue — not a rewrite. »*

> *« 4. RESPECT THE TIER GATE. Don't add steps "for thoroughness." Don't drop steps "for budget." The tier is a binding contract. »*

*Glose* : la règle 4 traite les deux dérives symétriques d'un agent zélé — en ajouter « pour bien faire » et en retirer « pour économiser ». Ailleurs le texte insiste : *« The tier classification is a product decision: simple queries should produce fast, right-sized answers. Trust the classification. »*

**Choix de design à retenir** : la **modularisation par fichiers annexes** (une skill par étape) n'est pas ici une commodité de lecture mais la réponse à un mode d'échec mesuré ; le **gabarit rendu à l'installation** rend les paramètres d'échelle inspectables dans les fichiers eux-mêmes plutôt que cachés dans du code ; et la **redondance des mémoires externes** est assumée comme un coût nécessaire.

## GrapheDeConnaissance

- Jordan Gibbs —a_créé→ hyperresearch (METHODOLOGIE, 0.97)
- hyperresearch —utilise→ Claude Code (TECHNOLOGIE, 0.97)
- hyperresearch —permet→ de transformer un agent de codage en agent de recherche documentaire profonde (AFFIRMATION, 0.95)
- skill d'entrée routeur —résout→ l'éviction par compaction de la procédure d'une étape dans un pipeline long (AFFIRMATION, 0.96)
- hyperresearch —affirme_que→ une skill unique de 1200 lignes se fait évincer du contexte et l'orchestrateur en oublie silencieusement des étapes (CITATION, 0.95)
- verrouillage d'outils —permet→ de rendre une réécriture mécaniquement impossible plutôt que déconseillée (AFFIRMATION, 0.95)
- verrouillage d'outils —surpasse→ une consigne de prompt pour garantir un comportement d'agent (AFFIRMATION, 0.92)
- hyperresearch —recommande→ de ne modifier un rapport synthétisé que par retouches chirurgicales, jamais par régénération (AFFIRMATION, 0.95)
- prompt utilisateur verbatim —fait_partie_de→ contrat canonique relu par chaque étape et chaque sous-agent (AFFIRMATION, 0.93)
- audit d'indépendance des sources —réduit→ le poids d'un consensus apparent formé de reprises d'un même communiqué (AFFIRMATION, 0.94)
- vérification de l'intégrité des citations —résout→ l'expédition de citations hallucinées, en exigeant leur présence verbatim dans le corpus (AFFIRMATION, 0.95)
- balayage de rétractation —s_applique_à→ chaque DOI cité au moment de l'expédition, y compris sur des sources réutilisées (AFFIRMATION, 0.92)
- hyperresearch —affirme_que→ le texte récupéré du web est une donnée et jamais une instruction (CITATION, 0.96)
- clôture untrusted-source —réduit→ le risque d'injection de prompt par une page web lue par un agent (AFFIRMATION, 0.94)
- notes produites par les sous-agents du pipeline —s_oppose_à→ les corps récupérés du web, servis sous clôture — frontière de confiance par provenance (AFFIRMATION, 0.9)
- récupération en accès ouvert —résout→ la citation d'un article payant lu seulement en abstract, comme s'il avait été lu (AFFIRMATION, 0.94)
- hyperresearch —utilise→ Unpaywall (TECHNOLOGIE, 0.93)
- hyperresearch —utilise→ Europe PMC (TECHNOLOGIE, 0.93)
- note rescued —affirme_que→ ni le titre, ni les auteurs, ni le corps ne proviennent de l'URL déclarée en source (AFFIRMATION, 0.93)
- vault hyperresearch —est_basé_sur→ markdown comme source de vérité et index SQLite reconstructible comme cache (AFFIRMATION, 0.95)
- vault hyperresearch —converge_avec→ l'architecture médaillon d'un corpus de veille en fichiers (CONCEPT, 0.85)
- score de qualité de source —est_basé_sur→ type de source, utilité constatée, autorité de citation avec rétractations, et centralité PageRank interne (AFFIRMATION, 0.92)
- vérification —s_oppose_à→ le paramétrage par registre, qui module les critiques mais jamais le contrôle des citations (AFFIRMATION, 0.93)
- hyperresearch —affirme_que→ le gate de lint attrape les défaillances structurelles mais ne garantit pas l'exactitude factuelle (CITATION, 0.95)
- hyperresearch —mesure→ une position de tête sur DeepResearch-Bench RACE, présentée comme projection prospective auto-administrée sans validation tierce (MESURE, 0.75)
- hyperresearch —utilise→ modèles Anthropic Opus et Sonnet via un roster de seize sous-agents (AFFIRMATION, 0.93)
- hyperresearch —s_oppose_à→ la résolution automatique des CAPTCHA, de la double authentification et des connexions (AFFIRMATION, 0.94)

---
Canonical: https://www.thekb.eu/es/fiches/skill-gibbs-hyperresearch-2026-08-03/