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

## Veille

Voce **Skill** (non un articolo): **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 di Claude Code** + una CLI + un server MCP + un'interfaccia 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 step adattiva per livello** (`light` ~30-40 min → `full` ~1,5-2,5 h → `dissertation` 4-8 h e 25.000-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 — e la più istruttiva — è documentata insieme al suo modo di fallimento**: la skill di ingresso è un **router leggero** che non contiene alcuna procedura, ogni step 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 triplice bozza. L'orchestratore ha dimenticato la procedura, ha scritto un'unica bozza e ha prodotto un report dal punteggio piatto. »* **Due principi portanti**: *« Applica patch, non rigenerare mai »* — dopo la sintesi sono possibili solo ritocchi chirurgici tramite `Edit`, poiché il patcher e l'auditor di rifinitura sono **bloccati agli strumenti `[Read, Edit]` a livello di allowlist di Claude Code**, cosicché *« fisicamente non possono scrivere (Write) una nuova bozza »*; e *« la query di ricerca canonica è vangelo »* — il prompt testuale viene persistito una volta in `query.md` e riletto da ogni step e da ogni subagente. **Sedici subagenti** con ruolo e modello configurabili (fetcher e cite-checker su Sonnet, critici/sintetizzatore/patcher su Opus). **Il vault** è un archivio markdown persistente indicizzato in SQLite — *« Markdown è verità, SQLite è cache »* — con un ciclo di vita delle note (`draft → review → evergreen`, `stale → deprecated → archive`), provenienza tracciabile, un punteggio di qualità composito (tipo di fonte, autorevolezza citazionale via OpenAlex/Semantic Scholar **con indicatori di ritrattazione**, PageRank interno) e un **audit di indipendenza** che raggruppa le copie sindacate — *« cinque ristampe di un comunicato stampa pesano quanto un'unica fonte »*. **Tre gate meccanici prima della pubblicazione**: integrità delle citazioni (ogni passaggio citato deve esistere **testualmente** in una nota del vault), una scansione delle ritrattazioni aggiornata su ogni DOI citato, e la verifica del collegamento citazione-frase da parte di un LLM scettico. ⚠️ **Riserva importante da segnalare**: l'affermazione di apertura — *« attualmente in testa alla classifica DeepResearch-Bench RACE »* — è contraddetta dalla sua stessa nota a piè di pagina, *« proiezione prospettica da un pilota stratificato… La validazione di terze parti è in sospeso »*. Una **proiezione** non è una classifica, eppure il grafico la colloca comunque 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 step, tier, light, full, dissertation, gear, profilo di scala, router leggero, caricamento differito, compattazione del contesto, espulsione della procedura, skill per step, patch mai rigenerare, ritocco chirurgico, tool-locking, bloccato agli strumenti, allowlist, Read Edit, query canonica, prompt testuale, vangelo, subagenti, fetcher, loci-analyst, depth-investigator, draft-orchestrator, sintetizzatore, 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, ship gate, lint, prompt injection, untrusted-source, testo web come dato, SSRF, Unpaywall, Europe PMC, accesso aperto, nota rescued, nothing_from_source, versione di record, escalation al browser, Claude-in-Chrome, CAPTCHA mai risolto automaticamente, budget della run, ripresa della run, MCP, DeepResearch-Bench, proiezione non validata, 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 un progetto open source ad alta densità tecnica, che raddoppia come **argomento di superiorità**. Il README non si limita a spiegare: **argomenta**, sezione per sezione, sotto titoli che sono tesi (*« Perché vince »*, *« Classifica delle fonti: la qualità è persistente, non impressioni »*, *« Il web è input ostile »*, *« Testo integrale ad accesso aperto: leggere 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 in un 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 didattico che supera il suo valore promozionale**: si imparano i modi di fallimento della ricerca approfondita agentica anche senza mai installare lo strumento.

**Registro operativo imposto all'agente** ("tono" nel senso delle voci skill): **imperativo, contrattuale, in maiuscolo per enfasi**. *« NON EMETTERE MAI TESTO NUDO MENTRE I TASK SONO IN ESECUZIONE »*, *« RISPETTA IL GATE DEL TIER »*, *« APPLICA PATCH, NON RIGENERARE MAI »*, *« ARGOMENTA, NON LIMITARTI A RIFERIRE »*. All'orchestratore viene esplicitamente tolto il lavoro stesso: *« Non svolgi TU il lavoro di alcuno step. Lo fanno le skill di step. Tu ti limiti a sequenziarle. »* Il prompt dell'utente viene chiamato **vangelo** — tre volte.

**Tratto notevole**: un'**onestà selettiva**. La sezione *« Cosa non fa »* è candida (*« Il gate di lint intercetta i fallimenti strutturali… Non può garantire l'accuratezza fattuale, quella resta una vostra responsabilità »*), gli avvertimenti sulle versioni dei preprint sono scrupolosi, e l'obbligo di fornire il proprio `contact_email` per Unpaywall è giustificato da un ragionamento collettivo (*« distribuire un placeholder condiviso farebbe finire quel placeholder sotto rate limiting per tutti gli utenti di hyperresearch contemporaneamente »*). Questo rigore rende ancora più visibile **l'unico punto in cui viene meno**: l'affermazione sulla classifica.

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

## Pense-betes

- **Natura**: **harness di ricerca approfondita** distribuito come pacchetto di **20 skill di Claude Code** + CLI Python + server MCP + interfaccia web locale. Installazione via `pip install hyperresearch && hyperresearch install`, poi `/hyperresearch <topic>`. MIT, Python 3.11-3.13.
- **⭐⭐ La lezione architetturale, con il suo modo di fallimento documentato** — la parte più trasferibile, indipendente dallo strumento: la skill di ingresso è un **router** che non contiene **alcuna** procedura, solo l'ordine di invocazione. Giustificazione testuale: *« V7 era un'unica skill di 1200 righe che veniva compattata via prima che il Layer 4 avesse bisogno della sua procedura di triplice bozza. L'orchestratore ha dimenticato la procedura, ha scritto un'unica bozza e ha prodotto un report dal punteggio piatto. V8 risolve il problema alla fonte: la procedura di ogni step viene caricata nel contesto solo nel momento in cui serve, fresca, senza rischio di espulsione. »* → **Una pipeline lunga non perde i suoi step perché il modello dimentica, ma perché il contesto viene espulso**, e la correzione è strutturale: una skill per step, caricata all'invocazione. È esattamente la disciplina di [[lassiege-usine-logicielle-heure-ia-2026-07-28]] ("il contesto permanente porta l'indice, non il contenuto") **scoperta in modo indipendente su un terreno diverso**. Una convergenza degna di nota.
- **⭐ Il tool-locking come garanzia fisica**: il patcher e l'auditor di rifinitura sono *« bloccati agli strumenti `[Read, Edit]` a livello di allowlist di Claude Code, cosicché fisicamente non possono scrivere (Write) una nuova bozza »*, con limiti per-hunk che rendono *« riscrivila e basta » meccanicamente impossibile*. → **All'agente non viene detto di non riscrivere — gli viene tolto lo strumento di scrittura.** Stessa famiglia di *« un hook o un test viene applicato ogni volta »* ([[lassiege-usine-logicielle-heure-ia-2026-07-28]]) e dell'anello di vincoli in [[sfeir-code-review-anneau-contraintes-2026-07-30]]: **l'impossibilità meccanica batte l'istruzione.** Corollario operativo: un rilievo della critica che non rientra in un piccolo ritocco **si trasforma in un problema strutturale** invece di innescare una riscrittura.
- **I sedici step, in tre blocchi** (conta più la struttura del dettaglio): **inquadramento** (1 scomposizione + matrice di copertura + classificazione del tier, 1.5 suddivisione in capitoli) → **corpus e analisi** (2 scansione di ampiezza, 3 grafo delle contraddizioni, 4 analisi dei loci, 5 indagini di approfondimento parallele, 6 riconciliazione tra loci, 7 tensioni tra fonti, 8 critica del corpus "quale fonte ribalterebbe questo?" + colmatura mirata delle lacune, 9 sintesi delle evidenze) → **scrittura e audit** (10 triplice bozza 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** — una distinzione netta e riutilizzabile: i **tier** instradano in base alla query e decidono **quali step vengono eseguiti**; i **gear** (profili di scala) decidono **quanto** — obiettivi di fonti, budget di profondità, lunghezza — e *« sopravvivono alle reinstallazioni »*, entrando in vigore alla run successiva, **mai a metà run**; le **leve** (`register`, `domain_notes`, `inference_depth`) decidono **con quale voce** esce il testo — `teach` / `survey` / `analyze` / `advocate`. ⭐ Dettaglio fine: le leve atterrano in **shim iniettati nei prompt dei subagenti**, *« così i critici si muovono con il registro invece di disfarlo »* — nel registro `survey`, il critico dialettico segnala una rappresentazione ingiusta piuttosto che una mancanza di impegno. **Ma**: *« Il cite-checker e lo ship gate non ricevono alcuno shim. La verifica non si ammorbidisce mai in base alla modalità. »* → **La verifica è l'unica fase esente dallo stile.** Un'eccellente regola di design.
- **⭐ I tre gate meccanici prima della pubblicazione** (la parte migliore del dispositivo, direttamente trasferibile a qualsiasi corpus documentale): 1. **quote-integrity** — ogni porzione citata tra virgolette deve esistere **testualmente** in una nota del vault; *« le citazioni allucinate non possono essere pubblicate »*. 2. **retracted-citations** — citare una fonte ritrattata senza segnalarlo è un **errore bloccante**, con una scansione delle ritrattazioni **aggiornata al momento della pubblicazione su ogni DOI citato**, incluse le fonti riutilizzate da run precedenti. *« una ritrattazione pubblicata ieri viene intercettata oggi »*. 3. **numeric-consistency** — i numeri non riconducibili a un'evidenza vengono segnalati. Più il **cite-check**: un LLM scettico campiona se la fonte citata **supporta effettivamente la frase** che sostiene.
- **⭐ L'audit di indipendenza — l'idea più immediatamente riutilizzabile**: le copie sindacate e derivate vengono raggruppate, cosicché *« cinque ristampe di un comunicato stampa pesano quanto un'unica fonte »*. **Il numero di fonti concordanti smette di essere un argomento nel momento in cui discendono tutte dallo stesso comunicato stampa.** Rilevante per qualsiasi pratica di veille tecnologica: la ridondanza da ristampa si traveste da consenso.
- **Punteggio di qualità composito persistente**: tipo di fonte + utilità osservata alla lettura + autorevolezza citazionale (OpenAlex / Semantic Scholar, **con indicatori di ritrattazione**) + **PageRank** sul grafo interno del vault. Le fonti ritrattate vengono **azzerate**. *« La qualità è persistente, non impressioni. »*
- **⭐⭐ La difesa contro il prompt injection — la più seria vista in un harness open**: *« Il testo recuperato è dato, mai istruzioni. »* Ogni corpo recuperato dal web viene servito dentro un recinto `<untrusted-source url="...">` con un preambolo che lo tratta come dato, **su entrambi i percorsi che servono corpi di testo** (`note show` e `search`). Dettagli che mostrano come la minaccia sia stata presa sul serio:
- le note scritte dai subagenti stessi della pipeline passano **senza recinto** → **confine di fiducia basato sulla provenienza**, non sul contenuto;
- i recinti di chiusura **contraffatti** trovati in un corpo recuperato vengono neutralizzati **ma lasciati visibili per l'analisi forense**;
- l'attributo `url` viene sottoposto a escaping e i suoi caratteri di controllo vengono rimossi;
- in `search`, l'avvolgimento avviene **dopo** il troncamento al budget di token, *« così il recinto di chiusura non può mai essere reciso »* — il dettaglio che tradisce come il bypass sia stato effettivamente cercato attivamente;
- gli URL risolti tramite API di terze parti vengono verificati (schema, credenziali incorporate, risoluzione instradabile pubblicamente) → difesa **SSRF**;
- i prompt di fetcher, investigatore e writer portano una clausola che vieta di **far transitare (laundering)** direttive da una pagina recintata verso l'output fidato. → Da confrontare con *« un confine di sicurezza che si basa su un'istruzione del prompt non è un confine »* ([[sfeir-anthropic-sdlc-ai-native-securise-2026-07-26]]): qui il recinto è **meccanico** e l'istruzione si limita a rinforzarlo. Stessa logica di trattare il contenuto osservato come dato presente in [[valente-zalewski-beyond-zero-enterprise-security-ai-era-2026-07-20]].
- **⭐ L'igiene epistemica sulle fonti a pagamento — notevole e rara**: un articolo a pagamento entrerebbe normalmente nel vault come un abstract di ~1.500 caratteri, che il report citerebbe poi *« come se fosse stato letto »*. hyperresearch interroga **Unpaywall** ed **Europe PMC** per una copia ad accesso aperto legale e memorizza **quel testo al suo posto**, dichiarando la sostituzione **in quattro punti** (banner nel corpo, frontmatter `oa_*`, blocco JSON `body_is_not_from_source: true`, output della CLI). E, cosa cruciale, viene distinto un terzo stato: la nota **"rescued"**, quando la fonte **non ha potuto essere letta affatto** — `nothing_from_source: true`, un banner che dichiara che l'URL non è mai stato letto, *« il titolo, gli autori e ogni parola del corpo appartengono alla copia ad accesso aperto »*. Avvertenza sulla versione: Unpaywall può restituire un manoscritto accettato o un preprint sottomesso, da verificare prima di qualsiasi citazione diretta. → **Il sistema distingue "ho letto questo" da "ho letto un sostituto" da "non ho mai letto la fonte"**, e porta questa distinzione nell'artefatto. **Direttamente trasferibile a una pratica di veille tecnologica.**
- **Il vault, e la sua inquietante vicinanza a questo stesso repository**: *« Markdown è verità, SQLite è cache »* — indice completamente ricostruibile (`hyperresearch sync`), note in markdown + frontmatter YAML leggibili senza lo strumento, versionabili in git, esportabili/importabili, **ciclo di vita curato** (`draft → review → evergreen` oppure `stale → deprecated → archive`) *« che impedisce a un vault di diventare una discarica di pagine lette a metà »*, provenienza via `--suggested-by` con una **regola di lint** che rileva componenti disconnesse, hub, backlink, wikilink. ⭐ **Questa è l'architettura di questo stesso corpus di veille tecnologica, scoperta in modo indipendente**: sorgente markdown, indice generato come cache, gate di lint, doctor, wikilink. Ciò che hyperresearch ha in più e questo corpus non ha: **punteggio di qualità per fonte, audit di indipendenza, scansione delle ritrattazioni, ricerca semantica opzionale, stato di ciclo di vita esplicito**. Una pista di ispirazione seria per `scripts/`.
- **Ripresa e budget**: ogni run dispone di uno spazio isolato (`research/runs/<tag>/`) e di un **manifest** che funge da *« memoria durevole »* — una run interrotta riprende esattamente dallo step morto (`run resume`). `run init --budget 50` **blocca** la run una volta superato il tetto *« invece di lasciarla gonfiare silenziosamente »*. Le run concorrenti non entrano in collisione.
- **⚠️⚠️ La riserva da segnalare sistematicamente — l'affermazione sul benchmark**: il README dichiara fin da subito che lo strumento *« attualmente è in testa alla classifica DeepResearch-Bench RACE (benchmark interno) »*, grafico incluso, collocandolo davanti a Grep Deep Research, Cellcog Max, nvidia-aiq, **Gemini Deep Research** e **OpenAI Deep Research**. La nota sotto il grafico dice qualcos'altro: *« Proiezione prospettica da un pilota stratificato rispetto allo snapshot della classifica DeepResearch-Bench. La validazione di terze parti è in sospeso. »* → **Una proiezione prospettica, autosomministrata, da un pilota stratificato, senza validazione di terze parti, non è una classifica.** Le due affermazioni non sono compatibili, ed è l'unico punto del repository in cui il rigore mostrato altrove viene meno. **Non citare mai la classifica; citare l'impostazione.**
- **⚠️ Altri limiti, alcuni riconosciuti dall'autore**:
- **Dipendenza da Anthropic**: *« Funziona su modelli Anthropic tramite il roster di subagenti »* — Opus per i critici, il sintetizzatore e il patcher, Sonnet per i fetcher. Un porting verso Codex è esplicitamente accolto con favore ma non realizzato (*« Se qualcuno vuole portarlo su Codex, apra una PR! »*).
- **Costo reale non quantificato in euro**: `premier` punta a 100-130 fonti in sola scansione e ~3-5 h; `dissertation` punta a 300-450 fonti e 4-8 h. Il budget è limitato in "spesa equivalente in API", non in costo osservato.
- **Il limite onesto, degno di citazione**: *« Il gate di lint intercetta i fallimenti **strutturali**… Non può garantire l'**accuratezza fattuale**, quella resta una vostra responsabilità. »* → **Verifica strutturale ≠ accuratezza fattuale.** L'intero dispositivo garantisce che una citazione esista, non che sia vera.
- **Un confine netto e benvenuto**: *« CAPTCHA, 2FA e login non vengono mai risolti automaticamente »* — vengono escalati e restituiti all'operatore umano.
- **Superficie di dipendenza**: 20 skill + 16 subagenti + una CLI che pilota un browser autenticato, su un repository di meno di quattro mesi. L'avvertimento di [[lassiege-usine-logicielle-heure-ia-2026-07-28]] si applica pienamente (*« qualsiasi skill, MCP o codice importato dall'esterno deve essere esaminato con attenzione »*).
- **Meta / da collegare**: l'istanza più compiuta dell'harness engineering di [[osmani-agent-harness-engineering-2026-04-19]]; converge in modo indipendente con [[lassiege-usine-logicielle-heure-ia-2026-07-28]] sul caricamento differito del contesto e sull'eseguibile che batte l'istruzione; stessa dottrina del confine meccanico di [[sfeir-anthropic-sdlc-ai-native-securise-2026-07-26]] e [[valente-zalewski-beyond-zero-enterprise-security-ai-era-2026-07-20]]; affinità di forma con le altre voci skill del corpus, [[skill-pocock-grill-with-docs-2026-06]] e [[akhouri-adhd-ideation-divergente-parallele-2026-07-20]]; da leggere insieme a [[agent-skills-anthropic-2025-10-16]], [[shihipar-claude-code-lessons-building-skills-2026-06-03]] e [[vincent-superpowers-agentic-skills-framework-github-2026-04-02]] sulla meccanica delle skill; la critica avversariale parallela si collega alla domanda sollevata da [[monperrus-end-of-code-review-agents-supersede-2026-06-11]] su cosa possa portare una revisione automatizzata.

## 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 ad aprile. L'installazione porta con sé **20 skill**, una CLI, un server MCP e un'interfaccia web locale.

**La pipeline** esegue 16 step adattivi su livelli: `light` (~30-40 min) per domande circoscritte, `full` (1,5-2,5 h) per analisi argomentative 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 step vengono eseguiti, i **gear** decidono quanto, le **leve** (`teach`/`survey`/`analyze`/`advocate`) decidono con quale voce esce il report.

**L'architettura risponde a un fallimento documentato.** La skill di ingresso è un **router leggero** senza alcuna procedura: *« 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 step vive nella propria skill, caricata fresca al momento dell'invocazione — una pipeline lunga non perde i suoi step per dimenticanza, ma per espulsione dal contesto.

**Due principi portanti.** *« Applica patch, non rigenerare mai »*: dopo la sintesi sono possibili solo ritocchi chirurgici, poiché il patcher è **bloccato agli strumenti `[Read, Edit]`** a livello di allowlist, cosicché *« fisicamente non può scrivere (Write) una nuova bozza »* — l'impossibilità meccanica sostituisce l'istruzione. E *« la query di ricerca canonica è vangelo »*: il prompt testuale viene persistito e riletto da ogni step.

**La verifica è l'unica fase esente dallo stile** — le leve iniettano shim nei prompt dei critici, ma *« il cite-checker e lo ship gate 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 è verità, SQLite è cache »* — con un ciclo di vita delle note, provenienza, un punteggio di qualità composito e un **audit di indipendenza**: *« cinque ristampe di un comunicato stampa pesano quanto un'unica fonte »*. I corpi recuperati dal web vengono serviti dentro un recinto `<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 afferma che si tratta di una *« proiezione prospettica da un pilota stratificato »* senza validazione di terze parti. Citare l'impostazione, 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)
- 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/it/fiches/skill-gibbs-hyperresearch-2026-08-03/