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

## Veille

Voce **Skill**: **hyperresearch** di **Jordan Gibbs** è un **harness di ricerca approfondita** che trasforma Claude Code in un agente di ricerca documentale, distribuito come pacchetto PyPI (MIT, Python 3.11-3.13) che installa **20 skill Claude Code**, una CLI, un server MCP e una UI web locale. Osservato il **3 agosto 2026**: 1.568 stelle, 170 fork, repository creato il 9 aprile 2026, ultimo push il 1° agosto. **Il nucleo è una pipeline a 16 passaggi adattiva per livelli (tier)** — `light` (~30-40 min), `full` (~1,5-2,5 h), `dissertation` (4-8 h, da 25.000 a 80.000 parole su 300-450 fonti) — che prende un prompt e restituisce un report sottoposto ad audit avversariale con provenienza completa. **La decisione architetturale centrale è documentata insieme al suo modo di fallimento**: la skill d'ingresso è un **router leggero (thin router)** senza procedura propria, ogni passaggio vive nella propria skill caricata **fresca al momento dell'invocazione**, perché la versione precedente era *« una singola skill di 1200 righe che veniva compattata via prima che il Layer 4 avesse bisogno della sua procedura di triplo abbozzo. L'orchestratore ha dimenticato la procedura, ha scritto un'unica bozza e ha prodotto un report dal punteggio piatto. »* **Due principi portanti.** *« Patch, mai rigenerare »*: dopo la sintesi, sono possibili solo ritocchi chirurgici con `Edit`, con il patcher e l'auditor di rifinitura bloccati sugli strumenti (`tool-locked`) a `[Read, Edit]` a livello di allowlist di Claude Code, in modo che *« non possano fisicamente scrivere (Write) una nuova bozza »*. *« La query di ricerca canonica è vangelo »*: il prompt testuale viene salvato una sola volta in `query.md` e riletto da ogni passaggio e da ogni subagente. **Sedici subagenti** con ruolo e modello configurabili (i fetcher e il cite-checker su Sonnet, i critici, il synthesizer e il patcher su Opus). **Il vault** è un archivio markdown persistente indicizzato in SQLite — *« Markdown è la verità, SQLite è la cache »* — con un ciclo di vita delle note (`draft → review → evergreen`, `stale → deprecated → archive`), provenienza tracciabile, un punteggio di qualità composito (tipo di fonte, autorità citazionale tramite OpenAlex e Semantic Scholar con segnalazioni di ritrattazione, PageRank interno), e un **audit di indipendenza** che raggruppa le copie sindacate — *« cinque ristampe di uno stesso comunicato stampa pesano quanto un'unica fonte »*. **Tre gate meccanici prima della pubblicazione**: l'integrità delle citazioni (ogni citazione riportata deve esistere **testualmente** in una nota del vault), una scansione delle ritrattazioni aggiornata su ogni DOI citato, e una verifica del collegamento citazione-frase da parte di un LLM scettico. **Riserva da segnalare**: l'affermazione d'apertura — *« attualmente in testa alla classifica DeepResearch-Bench RACE »* — è contraddetta dalla propria stessa nota a piè di pagina, *« proiezione prospettica da un pilota stratificato… la convalida da parte di terzi è in sospeso »*. Una proiezione non è una classifica, eppure il grafico la colloca davanti a Gemini e 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, ricerca approfondita, harness di ricerca, Claude Code, pipeline a 16 passaggi, tier, light, full, dissertation, gear, profilo di scala, router leggero, lazy loading, compattazione del contesto, espulsione della procedura, skill per passaggio, patch, mai rigenerare, modifica chirurgica, blocco degli strumenti, bloccato sugli strumenti, allowlist, Read Edit, query canonica, prompt testuale, vangelo, subagenti, fetcher, loci-analyst, depth-investigator, draft-orchestrator, synthesizer, critici avversariali, critico dialettico, cite-checker, patcher, auditor di rifinitura, vault, markdown come fonte di verità, cache SQLite, indice ricostruibile, ciclo di vita delle note, evergreen, deprecated, provenienza, suggested-by, punteggio di qualità, PageRank, OpenAlex, Semantic Scholar, ritrattazione, audit di indipendenza, sindacazione, quote-integrity, numeric-consistency, gate di pubblicazione, lint, prompt injection, untrusted-source, testo web come dato, SSRF, Unpaywall, Europe PMC, accesso aperto, nota recuperata, nothing_from_source, versione definitiva, escalation del browser, Claude-in-Chrome, CAPTCHA mai risolto, budget della corsa, run resume, MCP, DeepResearch-Bench, proiezione non convalidata, 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

**Profilo**: documentazione di progetto open source ad alta densità tecnica, che funge al contempo da **arringa a favore della propria superiorità**. Il README non si limita a spiegare: **argomenta**, sezione per sezione, sotto titoli che sono vere e proprie tesi (*« Perché vince »*, *« Classifica delle fonti: la qualità è persistente, non è una sensazione »*, *« Il web è un input ostile »*, *« Testo integrale ad accesso aperto: leggi questo prima di citare »*).

**Stile**: un registro da ingegnere che spiega un meccanismo attraverso il problema che risolve, quasi sempre in due tempi — prima il modo di fallimento, poi la correzione. *« Un articolo chiuso entra normalmente nel vault come un abstract di 1.500 caratteri che il report cita poi come se fosse stato letto »*, poi la sostituzione ad accesso aperto. *« V7 era un'unica skill di 1200 righe che veniva compattata via »*, poi il router. Questa forma conferisce al testo **un valore più pedagogico che promozionale**: i modi di fallimento della ricerca approfondita agentica vengono appresi anche da un lettore che non installa mai lo strumento.

**Registro operativo imposto all'agente** (« tono » nel senso della skill-card): **imperativo, contrattuale, maiuscole enfatiche**. *« NON EMETTERE MAI TESTO NUDO MENTRE I TASK SONO IN ESECUZIONE »*, *« RISPETTA IL TIER GATE »*, *« PATCH, MAI RIGENERARE »*, *« ARGOMENTA, NON LIMITARTI A RIFERIRE »*. All'orchestratore viene esplicitamente tolto il lavoro: *« Tu NON esegui il lavoro di alcun passaggio in prima persona. Lo fanno le skill dei passaggi. Tu ti limiti a sequenziarle. »* Il prompt dell'utente viene chiamato **vangelo** — per tre volte.

**Tratto notevole**: un'**onestà selettiva**. La sezione *« Ciò che non fa »* è schietta (*« Il gate di lint rileva i fallimenti strutturali… Non può garantire l'accuratezza fattuale, quella resta una tua responsabilità »*), le avvertenze sulle versioni preprint sono scrupolose, e l'obbligo di fornire il proprio `contact_email` per Unpaywall è giustificato da un argomento collettivo (*« distribuire un segnaposto condiviso farebbe finire quel segnaposto sotto rate-limit per tutti gli utenti di hyperresearch contemporaneamente »*). Questo rigore rende tanto più visibile **l'unico punto in cui vacilla**: l'affermazione sulla classifica.

**Frasi distintive**: *« Markdown è la verità, SQLite è la cache »*, *« Il testo recuperato è dato, mai istruzioni »*, *« cinque ristampe di uno stesso comunicato stampa pesano quanto un'unica fonte »*, *« non possono fisicamente scrivere una nuova bozza »*, *« la qualità è persistente, non è una sensazione »*, *« niente viene buttato via »*, *« ogni sessione parte più intelligente della precedente »*.

## Pense-betes

- **Natura**: un harness di ricerca approfondita distribuito come pacchetto di **20 skill Claude Code** + CLI Python + server MCP + UI web locale. `pip install hyperresearch && hyperresearch install`, poi `/hyperresearch <argomento>`. MIT, Python 3.11-3.13.
- **Inquadramento chiave**: la skill d'ingresso è un **router** senza procedura propria, ogni passaggio vive nella propria skill caricata fresca al momento dell'invocazione. ### La lezione architetturale, con il suo modo di fallimento documentato > *« V7 era un'unica skill di 1200 righe che veniva compattata via prima che il Layer 4 avesse bisogno della sua procedura di triplo abbozzo. L'orchestratore ha dimenticato la procedura, ha scritto un'unica bozza e ha prodotto un report dal punteggio piatto. V8 risolve questo alla radice: la procedura di ogni passaggio viene caricata nel contesto solo nel momento in cui serve, fresca, senza rischio di espulsione. »* Una pipeline lunga non perde i suoi passaggi perché il modello dimentica, ma per **espulsione dal contesto (context eviction)**, e la correzione è strutturale. Stessa disciplina del contesto persistente che porta l'indice anziché il contenuto in [[lassiege-usine-logicielle-heure-ia-2026-07-28]], scoperta in modo indipendente su un terreno diverso. ### Il blocco degli strumenti come garanzia Il patcher e l'auditor di rifinitura sono *« bloccati sugli strumenti a `[Read, Edit]` a livello di allowlist di Claude Code, così non possono fisicamente scrivere (Write) una nuova bozza »*, con limiti per porzione (`per-hunk caps`) che rendono *« semplicemente riscriverlo »* meccanicamente impossibile. All'agente non viene chiesto di non riscrivere — gli viene tolto lo strumento. Corollario: un rilievo critico che non rientra in un piccolo ritocco **si trasforma in un problema strutturale** invece di innescare una riscrittura. ### I sedici passaggi, in tre blocchi | Blocco | Passaggi | |---|---| | **Inquadramento** | 1 scomposizione + matrice di copertura + classificazione per tier; 1.5 partizionamento in capitoli | | **Corpus e analisi** | 2 scansione ad ampio raggio; 3 grafo delle contraddizioni; 4 analisi dei loci; 5 approfondimenti paralleli; 6 riconciliazione inter-loci; 7 tensioni tra fonti; 8 critica del corpus (*« quale fonte ribalterebbe questo? »*) + colmatura mirata delle lacune; 9 digest delle evidenze | | **Scrittura e audit** | 10 triplo abbozzo per angolazione; 11 sintesi; 12 quattro critiche avversariali parallele; 13 colmatura delle lacune post-critica; 14 patcher chirurgico; 14.5 verifica delle citazioni; 15 rifinitura; 16 audit di leggibilità | ### Tre leve di scala da non confondere | Leva | Decide | |---|---| | **Tier** (`tier`) | **quali passaggi** vengono eseguiti, instradati per query | | **Gear** (profili di scala) | **quanto** — obiettivi di fonti, budget di profondità, lunghezza; sopravvivono alle reinstallazioni, entrano in vigore alla corsa successiva, mai a metà corsa | | **Leve** (`register`, `domain_notes`, `inference_depth`) | **con quale voce** — `teach` / `survey` / `analyze` / `advocate` | Le leve atterrano come **shim iniettati nei prompt dei subagenti**, *« in modo che i critici si muovano insieme al registro invece di disfarlo »*. Ma: *« Il cite-checker e il gate di pubblicazione non ricevono alcuno shim. La verifica non si ammorbidisce mai in base alla modalità. »* La verifica è l'unica fase esente dallo stile. ### I tre gate meccanici prima della pubblicazione 1. **quote-integrity** — ogni porzione citata deve esistere **testualmente** in una nota del vault; *« le citazioni allucinate non possono essere pubblicate »*. 2. **retracted-citations** — citare una fonte ritrattata senza segnalarla è bloccante, con una scansione aggiornata **al momento della pubblicazione** su ogni DOI citato, comprese le fonti riutilizzate da corse precedenti: *« una ritrattazione pubblicata ieri viene individuata oggi »*. 3. **numeric-consistency** — i numeri non tracciabili a un elemento di prova vengono segnalati. A questo si aggiunge il **cite-check**: un LLM scettico campiona se la fonte citata sostenga effettivamente la frase che dovrebbe supportare. ### L'audit di indipendenza Le copie sindacate e derivate vengono raggruppate, in modo che *« cinque ristampe di uno stesso comunicato stampa pesino quanto un'unica fonte »*. Il numero di fonti concordanti smette di essere un argomento non appena discendono tutte dallo stesso comunicato stampa — rilevante per qualsiasi pratica di monitoraggio tecnologico. Punteggio di qualità composito e persistente: tipo di fonte, utilità osservata alla lettura, autorità citazionale (OpenAlex / Semantic Scholar con segnalazioni di ritrattazione), PageRank sul grafo interno. Le fonti ritrattate vengono azzerate: *« La qualità è persistente, non è una sensazione. »* ### La difesa contro il prompt injection *« Il testo recuperato è dato, mai istruzioni. »* Ogni corpo recuperato dal web viene servito all'interno di un recinto `<untrusted-source url="...">` con un preambolo *treat-as-data*, su entrambi i percorsi che servono i corpi di testo (`note show` e `search`). Dettagli che mostrano come la minaccia sia stata considerata a fondo:
- le note scritte dai subagenti passano **senza recinto** — il confine di fiducia è **per provenienza**, non per contenuto;
- i tag di recinto contraffatti all'interno di un corpo recuperato vengono neutralizzati **ma lasciati visibili** ai fini dell'analisi forense;
- l'attributo `url` viene sottoposto a escaping e i suoi caratteri di controllo vengono rimossi;
- in `search`, l'incapsulamento avviene **dopo** il troncamento al budget di token, *« in modo che il recinto di chiusura non possa mai essere reciso »*;
- gli URL risolti tramite API di terze parti vengono verificati (schema, credenziali incorporate, risoluzione instradabile pubblicamente) — difesa contro SSRF;
- i prompt del fetcher, dell'investigatore e dello scrittore vietano di far filtrare direttive da una pagina recintata verso l'output ritenuto affidabile. ### Igiene epistemica sulle fonti chiuse Un articolo protetto da paywall entrerebbe normalmente nel vault come un abstract di circa 1.500 caratteri, che il report citerebbe poi *« come se fosse stato letto »*. hyperresearch interroga **Unpaywall** ed **Europe PMC** alla ricerca di una copia legale ad accesso aperto e memorizza quel testo al suo posto, dichiarando la sostituzione in quattro punti (banner, frontmatter `oa_*`, blocco JSON `body_is_not_from_source: true`, output della CLI). Si distingue un terzo stato: la nota **« recuperata » (rescued)**, quando la fonte non ha potuto essere letta affatto — `nothing_from_source: true`, con un banner che dichiara che l'URL non è mai stato letto. Il sistema distingue così *« ho letto questo »*, *« ho letto un sostituto »* e *« non ho mai letto la fonte »*, e porta questa distinzione fino nell'artefatto. Avvertenza: Unpaywall può restituire un manoscritto accettato o un preprint sottomesso, da verificare prima di una citazione diretta. ### Il vault *« Markdown è la verità, SQLite è la cache »* — un indice interamente ricostruibile (`hyperresearch sync`), note markdown + frontmatter YAML leggibili senza lo strumento, versionabili con git, un ciclo di vita curato (`draft → review → evergreen` oppure `stale → deprecated → archive`) *« che impedisce a un vault di diventare un deposito di pagine lette a metà »*, provenienza tramite `--suggested-by` con una regola di lint che rileva componenti disconnesse, hub e backlink. È l'architettura di questo corpus di monitoraggio tecnologico, scoperta in modo indipendente. Ciò che hyperresearch aggiunge in più: punteggio di qualità per fonte, audit di indipendenza, scansione delle ritrattazioni, ricerca semantica opzionale, stato di ciclo di vita esplicito. Uno spunto da prendere in prestito per `scripts/`. ### Ripresa delle corse e budget Ogni corsa ha uno spazio di lavoro isolato (`research/runs/<tag>/`) e un manifest che funge da *« memoria durevole »*: una corsa interrotta riprende esattamente dal passaggio morto (`run resume`). `run init --budget 50` **blocca** la corsa quando il limite viene superato *« invece di lasciarla gonfiare silenziosamente »*. ### Riserve
- **L'affermazione sulla classifica non regge.** Il README dichiara *« attualmente in testa alla classifica DeepResearch-Bench RACE (benchmark interno) »* con un grafico che la colloca davanti a Gemini e OpenAI Deep Research; la nota sotto il grafico dice *« Proiezione prospettica da un pilota stratificato… La convalida da parte di terzi è in sospeso. »* Una proiezione da un pilota autosomministrato non è una classifica. Citare l'impostazione dello studio, mai la classifica.
- **Dipendenza da Anthropic**: *« Funziona su modelli Anthropic tramite l'elenco dei subagenti »* — Opus per i critici, il synthesizer e il patcher, Sonnet per i fetcher. Un porting su Codex è desiderato ma non realizzato.
- **Costo non quantificato**: `premier` punta a 100-130 fonti e ~3-5 h, `dissertation` a 300-450 fonti e 4-8 h; il limite di budget è espresso in *spesa equivalente API*, non in costo osservato.
- **Limite riconosciuto dall'autore**: *« Il gate di lint rileva i fallimenti strutturali… Non può garantire l'accuratezza fattuale, quella resta una tua responsabilità. »* La verifica strutturale non è accuratezza fattuale.
- **Confine invalicabile**: *« I CAPTCHA, la 2FA e i login non vengono mai risolti automaticamente »* — consolidati e restituiti all'utente umano.
- **Superficie di dipendenza**: 20 skill, 16 subagenti e una CLI che pilota un browser autenticato, su un repository con meno di quattro mesi di vita.

## RésuméDe400mots

**hyperresearch** (Jordan Gibbs, MIT, PyPI) trasforma Claude Code in un agente di ricerca approfondita. Osservato il 3 agosto 2026: 1.568 stelle, repository creato in aprile. L'installazione rilascia **20 skill**, una CLI, un server MCP e una UI web locale.

**La pipeline** esegue 16 passaggi adattivi per livello (tier): `light` (~30-40 min) per domande circoscritte, `full` (1,5-2,5 h) per un'analisi argomentativa con revisione avversariale, `dissertation` (4-8 h, 25.000-80.000 parole, 300-450 fonti) su richiesta esplicita. Tre leve distinte: i **tier** decidono quali passaggi vengono eseguiti, i **gear** decidono in che misura, le **leve** (`teach`/`survey`/`analyze`/`advocate`) decidono in quale voce esce il report.

**L'architettura risponde a un fallimento documentato.** La skill d'ingresso è un **router leggero** senza procedura propria: *« V7 era un'unica skill di 1200 righe che veniva compattata via… L'orchestratore ha dimenticato la procedura, ha scritto un'unica bozza e ha prodotto un report dal punteggio piatto. »* Ogni passaggio vive nella propria skill, caricata fresca al momento dell'invocazione — una pipeline lunga non perde i suoi passaggi per dimenticanza, ma per espulsione dal contesto (context eviction).

**Due principi portanti.** *« Patch, mai rigenerare »*: dopo la sintesi sono possibili solo modifiche chirurgiche, con il patcher **bloccato sugli strumenti a `[Read, Edit]`** a livello di allowlist, in modo che *« non possa fisicamente scrivere (Write) una nuova bozza »* — l'impossibilità meccanica sostituisce l'istruzione. E *« la query di ricerca canonica è vangelo »*: il prompt testuale viene salvato e riletto da ogni passaggio.

**La verifica è l'unica fase esente dallo stile** — le leve iniettano degli shim nei prompt dei critici, ma *« il cite-checker e il gate di pubblicazione non ricevono alcuno shim »*. Tre gate bloccano la pubblicazione: ogni citazione deve esistere **testualmente** nel vault, una fonte ritrattata non segnalata è un errore bloccante (con una scansione aggiornata su ogni DOI citato), e i numeri non tracciabili vengono segnalati.

**Il vault** è un archivio markdown persistente indicizzato in SQLite — *« Markdown è la verità, SQLite è la cache »* — con un ciclo di vita delle note, provenienza, un punteggio di qualità composito e un **audit di indipendenza**: *« cinque ristampe di uno stesso comunicato stampa pesano quanto un'unica fonte »*. I corpi dei testi recuperati dal web vengono serviti all'interno di un recinto (`fence`) `<untrusted-source>`: *« Il testo recuperato è dato, mai istruzioni. »*

**La riserva.** Il README rivendica il primo posto nella classifica DeepResearch-Bench; la sua stessa nota a piè di pagina chiarisce che si tratta di una *« proiezione prospettica da un pilota stratificato »* priva di convalida da parte di terzi. Citare l'impostazione dello studio, mai la classifica. L'autore riconosce inoltre che il lint *« non può garantire l'accuratezza fattuale »*.

## 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/it/fiches/skill-gibbs-hyperresearch-2026-08-03/