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

## Veille

Entrada de **Skill**: **hyperresearch**, de **Jordan Gibbs**, es un **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 y una interfaz web local. Observado el **3 de agosto de 2026**: 1.568 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 niveles** — `light` (~30-40 min), `full` (~1,5-2,5 h), `dissertation` (4-8 h, 25.000-80.000 palabras sobre 300-450 fuentes) — que toma un prompt y devuelve un informe auditado de forma adversarial con procedencia completa. **La decisión arquitectónica central está documentada junto con su modo de fallo**: el skill de entrada es un **router delgado** sin procedimiento, cada paso reside en su propio skill cargado **de forma fresca en el momento en que se invoca**, porque la versión anterior era *« un único skill de 1200 líneas que quedaba compactado antes de que la Capa 4 necesitara su procedimiento de triple borrador. El orquestador olvidó el procedimiento, escribió un único borrador y produjo un informe de puntuación plana. »* **Dos principios estructurales.** *« Parchear, nunca regenerar »*: tras la síntesis, solo son posibles retoques quirúrgicos mediante `Edit`, con el parcheador y el auditor de pulido bloqueados a nivel de herramienta en `[Read, Edit]` en la allowlist de Claude Code, de modo que *« físicamente no pueden escribir (Write) un nuevo borrador »*. *« La consulta canónica de investigación es palabra sagrada »*: el prompt textual se persiste una única 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 y parcheador en Opus). **La bóveda (vault)** es un almacén markdown persistente indexado en SQLite — *« Markdown es la verdad, SQLite es la caché »* — 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 y Semantic Scholar con marcadores de retractación, PageRank interno) y una **auditoría de independencia** que agrupa las copias sindicadas — *« cinco reimpresiones de un mismo comunicado de prensa pesan como una sola fuente »*. **Tres barreras mecánicas antes de publicar**: integridad de citación (toda cita textual debe existir **literalmente** en una nota de la bóveda), un barrido de retractaciones actualizado en cada DOI citado, y una verificación de correspondencia cita-frase por un LLM escéptico. **Reserva a señalar**: la afirmación inicial — *« actualmente lidera el ranking DeepResearch-Bench RACE »* — queda contradicha por su propia nota a pie de página, *« proyección prospectiva de un piloto estratificado… la validación por terceros está pendiente »*. Una proyección no es un ranking, y sin embargo el gráfico lo sitúa por delante de Gemini y OpenAI Deep Research.

## 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, deep research, research harness, Claude Code, pipeline de 16 pasos, tiers, light, full, dissertation, gear, perfil de escala, router delgado, carga diferida, compactación de contexto, desalojo de procedimiento, skill por paso, parchear nunca regenerar, edición quirúrgica, 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, caché SQLite, í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, puerta de publicación, lint, inyección de prompts, untrusted-source, texto web como dato, 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, que a la vez funciona como un **alegato de superioridad**. El README no se limita a explicar: **argumenta**, sección por sección, bajo encabezados que son tesis (*« Por qué gana »*, *« Ranking de fuentes: la calidad es persistente, no una sensación »*, *« La web es una entrada hostil »*, *« Texto completo de acceso abierto: leer esto antes de citar »*).

**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. *« Un artículo cerrado normalmente entra en una bóveda como un resumen de 1.500 caracteres que el informe cita luego como si se hubiera leído »*, y a continuación la sustitución por acceso abierto. *« V7 era un único skill de 1200 líneas que quedaba compactado »*, y a continuación el router. Esta forma otorga al texto **más valor pedagógico que promocional**: los modos de fallo de la investigación profunda agéntica se aprenden incluso por un lector que nunca instala la herramienta.

**Registro operativo impuesto al agente** (« tone » en el sentido de skill-card): **imperativo, contractual, mayúsculas de énfasis**. *« NEVER EMIT BARE TEXT WHILE TASKS ARE RUNNING »*, *« RESPECT THE TIER GATE »*, *« PATCH, NEVER REGENERATE »*, *« ARGUE, DON'T JUST REPORT »*. Al orquestador se le retira explícitamente el trabajo: *« You do NOT do the work of any step yourself. The step skills do. You just sequence them. »* El prompt del usuario recibe el nombre de **gospel** (palabra sagrada) — 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 preprint son escrupulosas, y la exigencia de aportar el propio `contact_email` para Unpaywall se justifica con un argumento colectivo (*« shipping a shared placeholder would get that placeholder rate-limited for every hyperresearch user at once »*). Este rigor hace tanto más visible el **único punto donde falla**: la afirmación de ranking.

**Frases distintivas**: *« 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**: un deep research harness distribuido como paquete de **20 skills de Claude Code** + CLI Python + servidor MCP + interfaz web local. `pip install hyperresearch && hyperresearch install`, luego `/hyperresearch <topic>`. MIT, Python 3.11-3.13.
- **Encuadre clave**: el skill de entrada es un **router** sin procedimiento, cada paso reside en su propio skill cargado de forma fresca en la invocación. ### La lección arquitectónica, con su modo de fallo documentado > *« V7 era un único skill de 1200 líneas que quedaba compactado antes de que la Capa 4 necesitara su procedimiento de triple borrador. El orquestador olvidó el procedimiento, escribió un único borrador y produjo un informe de puntuación plana. V8 corrige esto en origen: el procedimiento de cada paso se carga en el contexto solo en el momento en que se necesita, fresco, sin riesgo de desalojo. »* Un pipeline largo no pierde sus pasos porque el modelo olvide, sino por **desalojo de contexto**, y la corrección es estructural. Misma disciplina que el contexto persistente que transporta el índice y no el contenido en [[lassiege-usine-logicielle-heure-ia-2026-07-28]], descubierta de forma independiente en otro terreno. ### El bloqueo de herramientas como garantía El parcheador y el auditor de pulido están *« bloqueados a nivel de herramienta en `[Read, Edit]` en la allowlist de Claude Code, de modo que físicamente no pueden escribir (Write) un nuevo borrador »*, con topes por fragmento que hacen mecánicamente imposible el *« reescribirlo directamente »*. No se le pide al agente que no reescriba: se le retira la herramienta. Corolario: un hallazgo de crítica que no cabe en un retoque menor **escala a un problema estructural** en lugar de disparar una reescritura. ### Los dieciséis pasos, en tres bloques | Bloque | Pasos | |---|---| | **Encuadre** | 1 descomposición + matriz de cobertura + clasificación de nivel; 1.5 partición en capítulos | | **Corpus y análisis** | 2 barrido de amplitud; 3 grafo de contradicciones; 4 análisis de loci; 5 investigaciones profundas en paralelo; 6 reconciliación entre loci; 7 tensiones entre fuentes; 8 crítica del corpus (*« ¿qué fuente refutaría esto? »*) + relleno de lagunas dirigido; 9 resumen 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 lagunas post-crítica; 14 parcheador quirúrgico; 14.5 verificación de citas; 15 pulido; 16 auditoría de legibilidad | ### Tres palancas de escalado que no hay que confundir | Palanca | Decide | |---|---| | **Tiers** (`tier`) | **qué pasos** se ejecutan, enrutados por consulta | | **Gears** (perfiles de escala) | **cuánto** — objetivos de fuentes, presupuestos de profundidad, extensión; sobreviven a reinstalaciones, surten efecto en la siguiente ejecución, nunca a mitad de proceso | | **Levers** (`register`, `domain_notes`, `inference_depth`) | **con qué voz** — `teach` / `survey` / `analyze` / `advocate` | Las levers se aplican como **shims inyectados en los prompts de los subagentes**, *« de modo que los críticos se mueven con el registro en lugar de deshacerlo »*. Pero: *« el cite-checker y la puerta de publicación no reciben ningún shim en absoluto. La verificación nunca se suaviza según el modo. »* La verificación es la única etapa exenta de estilo. ### Las tres barreras mecánicas antes de publicar 1. **quote-integrity** — todo fragmento citado debe existir **literalmente** en una nota de la bóveda; *« las citas alucinadas no pueden publicarse »*. 2. **retracted-citations** — citar una fuente retractada sin señalarla es bloqueante, con un barrido actualizado **en el momento de publicar** sobre cada DOI citado, incluidas las fuentes reutilizadas de ejecuciones anteriores: *« una retractación publicada ayer se detecta hoy »*. 3. **numeric-consistency** — las cifras no trazables a una pieza de evidencia se marcan. A esto se añade **cite-check**: un LLM escéptico muestrea si la fuente citada respalda realmente la frase que sostiene. ### La auditoría de independencia Las copias sindicadas y derivadas se agrupan, de modo que *« cinco reimpresiones de un mismo comunicado de prensa pesan como una sola fuente »*. 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. Puntuación de calidad compuesta y persistente: tipo de fuente, utilidad observada en la lectura, autoridad de citación (OpenAlex / Semantic Scholar con marcadores de retractación), PageRank sobre el grafo interno. Las fuentes retractadas se llevan a cero: *« La calidad es persistente, no una sensación. »* ### La defensa contra la inyección de prompts *« El texto obtenido es dato, nunca instrucción. »* Todo cuerpo obtenido de la web se sirve dentro de una valla `<untrusted-source url="...">` con un preámbulo *treat-as-data*, en ambas rutas que sirven cuerpos (`note show` y `search`). Detalles que muestran que la amenaza fue pensada a fondo:
- las notas escritas por subagentes pasan **sin valla** — frontera de confianza **por procedencia**, no por contenido;
- las etiquetas de valla falsificadas dentro de un cuerpo obtenido se neutralizan **pero se dejan visibles** para análisis forense;
- el atributo `url` se escapa y sus caracteres de control se eliminan;
- en `search`, el envoltorio ocurre **después** del truncado al presupuesto de tokens, *« de modo que la valla de cierre nunca puede quedar seccionada »*;
- 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 prohíben blanquear directivas de una página vallada hacia una salida de confianza. ### Higiene epistémica sobre fuentes cerradas Un artículo de pago normalmente entraría en la bóveda como un resumen (abstract) de unos 1.500 caracteres, que el informe citaría luego *« como si se hubiera leído »*. hyperresearch consulta **Unpaywall** y **Europe PMC** en busca de una copia legal de acceso abierto y almacena ese texto en su lugar, señalando la sustitución en cuatro sitios (banner, frontmatter `oa_*`, bloque JSON `body_is_not_from_source: true`, salida de CLI). Se distingue un tercer estado: la nota **« rescatada »**, cuando la fuente no pudo leerse en absoluto — `nothing_from_source: true`, con un banner que indica que la URL nunca fue leída. El sistema distingue así *« leí esto »*, *« leí un sustituto »* y *« nunca leí la fuente »*, y traslada esa distinción al artefacto. Advertencia: Unpaywall puede devolver un manuscrito aceptado o un preprint enviado, a verificar antes de citarlo directamente. ### La bóveda *« Markdown es la verdad, SQLite es la caché »* — un índice totalmente reconstruible (`hyperresearch sync`), notas markdown + frontmatter YAML legibles sin la herramienta, versionable con git, un ciclo de vida curado (`draft → review → evergreen` o `stale → deprecated → archive`) *« que evita que una bóveda se convierta en un vertedero de páginas a medio leer »*, procedencia vía `--suggested-by` con una regla de lint que detecta componentes desconectados, hubs y backlinks. Esta es la arquitectura de este corpus de vigilancia tecnológica, descubierta de forma independiente. Lo que hyperresearch añade encima: puntuación de calidad por fuente, auditoría de independencia, barrido de retractaciones, búsqueda semántica opcional, estado de ciclo de vida explícito. Una pista digna de tomar prestada para `scripts/`. ### Reanudación de ejecuciones y presupuesto Cada ejecución tiene un espacio de trabajo aislado (`research/runs/<tag>/`) y un manifiesto que sirve de *« memoria duradera »*: una ejecución que se cae se reanuda exactamente en el paso muerto (`run resume`). `run init --budget 50` **bloquea** la ejecución al superarse el tope *« en lugar de dejar que se infle silenciosamente »*. ### Reservas
- **La afirmación de ranking no se sostiene.** El README afirma *« actualmente lidera el ranking DeepResearch-Bench RACE (evaluado internamente) »* con un gráfico que lo sitúa por delante de Gemini y OpenAI Deep Research; la nota bajo el gráfico dice *« Proyección prospectiva de un piloto estratificado… La validación por terceros está pendiente. »* Una proyección de un piloto autoadministrado no es un ranking. Citar el dispositivo, nunca el ranking.
- **Dependencia de Anthropic**: *« Funciona sobre modelos de Anthropic vía el elenco de subagentes »* — Opus para críticos, sintetizador y parcheador, Sonnet para fetchers. Se desea un puerto a Codex pero no está hecho.
- **Coste no cuantificado**: `premier` apunta a 100-130 fuentes y ~3-5 h, `dissertation` a 300-450 fuentes y 4-8 h; el tope de presupuesto se expresa en *gasto equivalente en API*, no en coste observado.
- **Límite reconocido por el autor**: *« La puerta de lint detecta fallos estructurales… No puede garantizar la exactitud factual, eso sigue siendo tu responsabilidad. »* La verificación estructural no es exactitud factual.
- **Frontera dura**: *« los CAPTCHA, el 2FA y los inicios de sesión nunca se resuelven de forma automática »* — se consolidan y se devuelven al humano.
- **Superficie de dependencia**: 20 skills, 16 subagentes y una CLI que maneja un navegador autenticado, sobre un repositorio de menos de cuatro meses.

## RésuméDe400mots

**hyperresearch** (Jordan Gibbs, MIT, PyPI) convierte Claude Code en un agente de investigación en profundidad. Observado el 3 de agosto de 2026: 1.568 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 solicitud explícita. Tres palancas distintas: los **tiers** deciden qué pasos se ejecutan, los **gears** deciden cuántos, las **levers** (`teach`/`survey`/`analyze`/`advocate`) deciden con qué voz sale el informe.

**La arquitectura responde a un fallo documentado.** El skill de entrada es un **router delgado** sin procedimiento: *« V7 era un único skill de 1200 líneas que quedaba compactado… El orquestador olvidó el procedimiento, escribió un único borrador y produjo un informe de puntuación plana. »* Cada paso reside en su propio skill, cargado de forma fresca en el momento de la invocación — un pipeline largo no pierde sus pasos por olvido, sino por desalojo de contexto.

**Dos principios estructurales.** *« Parchear, nunca regenerar »*: tras la síntesis, solo son posibles ediciones quirúrgicas, con el parcheador **bloqueado a nivel de herramienta en `[Read, Edit]`**, de modo que *« físicamente no puede escribir (Write) un nuevo borrador »* — la imposibilidad mecánica reemplaza a la instrucción. Y *« la consulta canónica de investigación es palabra sagrada »*: el prompt textual se persiste y es releído por cada paso.

**La verificación es la única etapa exenta de estilo** — las levers inyectan shims en los prompts de los críticos, pero *« el cite-checker y la puerta de publicación no reciben ningún shim »*. Tres barreras bloquean la publicación: toda cita debe existir **literalmente** en la bóveda, una fuente retractada no señalada es un error bloqueante (con un barrido actualizado en cada DOI citado), y las cifras no trazables se marcan.

**La bóveda (vault)** es markdown persistente indexado en SQLite — *« Markdown es la verdad, SQLite es la caché »* — con un ciclo de vida de nota, procedencia, una puntuación de calidad compuesta, y una **auditoría de independencia**: *« cinco reimpresiones de un mismo comunicado de prensa pesan como una sola fuente »*. Los cuerpos obtenidos de la web se sirven dentro de una valla `<untrusted-source>`: *« El texto obtenido es dato, nunca instrucción. »*

**La reserva.** El README afirma liderar el ranking DeepResearch-Bench; su propia nota a pie de página aclara que se trata de una *« proyección prospectiva de un piloto estratificado »* sin validación por terceros. Citar el dispositivo, nunca el ranking. El autor también reconoce que el lint *« no puede garantizar la exactitud factual »*.

## 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)
- hyperresearch —est_basé_sur→ markdown comme source de vérité et index SQLite reconstructible comme cache (AFFIRMATION, 0.95)
- 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/