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

## Veille

**Skill** entry (not an article): **hyperresearch** by **Jordan Gibbs** is a **deep research harness** that turns Claude Code into a document-research agent, shipped as a PyPI package (MIT, Python 3.11-3.13) installing **20 Claude Code skills** + a CLI + an MCP server + a local web UI. Observed on **August 3, 2026**: 1,568 stars, 170 forks, repo created April 9, 2026, last push August 1. **The core is a 16-step pipeline adaptive by tier** (`light` ~30-40 min → `full` ~1.5-2.5 h → `dissertation` 4-8 h and 25,000-80,000 words across 300-450 sources), which takes a prompt and returns a report **audited adversarially** with full provenance. **The central — and most instructive — architecture decision is documented alongside its failure mode**: the entry skill is a **thin router** containing no procedure at all, each step living in its own skill loaded **fresh at the moment it is invoked** — because the previous version 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. »* **Two load-bearing principles**: *« Patch, never regenerate »* — after synthesis, only surgical `Edit` touch-ups are possible, the patcher and the polish auditor being **tool-locked to `[Read, Edit]` at the Claude Code allowlist level**, so that they *« physically cannot Write a new draft »*; and *« canonical research query is gospel »* — the verbatim prompt is persisted once in `query.md` and re-read by every step and every subagent. **Sixteen subagents** with configurable role and model (fetchers and cite-checker on Sonnet, critics/synthesizer/patcher on Opus). **The vault** is a persistent markdown store indexed in SQLite — *« Markdown is truth, SQLite is cache »* — with a note lifecycle (`draft → review → evergreen`, `stale → deprecated → archive`), traceable provenance, a composite quality score (source type, citation authority via OpenAlex/Semantic Scholar **with retraction indicators**, internal PageRank) and an **independence audit** that groups syndicated copies — *« five reprints of one press release argue with the weight of one source »*. **Three mechanical gates before shipping**: citation integrity (any quoted passage must exist **verbatim** in a vault note), a retraction scan refreshed on every cited DOI, and citation-to-sentence linkage verification by a skeptical LLM. ⚠️ **Major reservation to flag**: the headline claim — *« currently leads the DeepResearch-Bench RACE leaderboard »* — is contradicted by its own footnote, *« forward-looking projection from a stratified pilot… Third party validation is pending »*. A **projection** is not a ranking, yet the chart places it ahead of Gemini and OpenAI Deep Research all the same.

## 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, 16-step pipeline, tiers, light, full, dissertation, gear, scale profile, thin router, deferred loading, context compaction, procedure eviction, skill per step, patch never regenerate, surgical touch-up, tool-locking, tool-locked, allowlist, Read Edit, canonical query, verbatim prompt, gospel, subagents, fetcher, loci-analyst, depth-investigator, draft-orchestrator, synthesizer, adversarial critics, dialectic critic, cite-checker, patcher, polish auditor, vault, markdown source of truth, SQLite cache, reconstructible index, note lifecycle, evergreen, deprecated, provenance, suggested-by, quality score, PageRank, OpenAlex, Semantic Scholar, retraction, independence audit, syndication, quote-integrity, numeric-consistency, ship gate, lint, prompt injection, untrusted-source, web text as data, SSRF, Unpaywall, Europe PMC, open access, rescued note, nothing_from_source, version of record, browser escalation, Claude-in-Chrome, CAPTCHA never solved, run budget, run resume, MCP, DeepResearch-Bench, unvalidated projection, 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

**Profile**: open-source project documentation with high technical density, doubled as a **superiority argument**. The README doesn't just explain: it **argues**, section by section, under headings that are theses (*« Why it wins »*, *« Source ranking: quality is persistent, not vibes »*, *« The web is hostile input »*, *« Open-access full text: read this before you cite »*).

**Style**: an engineer's register that explains a mechanism through the problem it solves, almost always in two beats — the failure mode first, then the fix. *« A closed paper normally enters a vault as a 1,500-character abstract that the report then cites as though it had been read »*, then the open-access substitution. *« V7 was one 1200-line skill that got compacted away »*, then the router. This form gives the text a **teaching value that exceeds its promotional value**: one learns the failure modes of agentic deep research even without ever installing the tool.

**Operational register imposed on the agent** ("tone" in the sense of skill entries): **imperative, contractual, capitalized for emphasis**. *« NEVER EMIT BARE TEXT WHILE TASKS ARE RUNNING »*, *« RESPECT THE TIER GATE »*, *« PATCH, NEVER REGENERATE »*, *« ARGUE, DON'T JUST REPORT »*. The orchestrator is explicitly stripped of the work itself: *« You do NOT do the work of any step yourself. The step skills do. You just sequence them. »* The user prompt is called **gospel** — three times.

**Notable trait**: a **selective honesty**. The *« What it doesn't do »* section is candid (*« The lint gate catches structural failures… It cannot guarantee factual accuracy, that's still your call »*), the preprint-version warnings are scrupulous, and the requirement to supply one's own `contact_email` for Unpaywall is justified by collective reasoning (*« shipping a shared placeholder would get that placeholder rate-limited for every hyperresearch user at once »*). This rigor makes the **one place where it slips** all the more visible: the leaderboard claim.

**Marker phrases**: *« 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

- **Nature**: **deep research harness** shipped as a package of **20 Claude Code skills** + Python CLI + MCP server + local web UI. Install via `pip install hyperresearch && hyperresearch install`, then `/hyperresearch <topic>`. MIT, Python 3.11-3.13.
- **⭐⭐ The architecture lesson, with its documented failure mode** — the most transferable part, independent of the tool: the entry skill is a **router** containing **no** procedure at all, only the invocation order. Textual justification: *« 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. »* → **A long pipeline doesn't lose its steps because the model forgets, but because context gets evicted**, and the fix is structural: one skill per step, loaded on invocation. This is exactly the discipline of [[lassiege-usine-logicielle-heure-ia-2026-07-28]] ("the permanent context carries the index, not the content") **discovered independently on different ground**. A convergence worth noting.
- **⭐ Tool-locking as a physical guarantee**: the patcher and the polish auditor are *« tool-locked to `[Read, Edit]` at the Claude Code allowlist level so they physically cannot Write a new draft »*, with per-hunk caps that make *« just rewrite it » mechanically impossible*. → **The agent isn't told not to rewrite — the write tool is taken away from it.** Same family as *« a hook or a test is enforced every time »* ([[lassiege-usine-logicielle-heure-ia-2026-07-28]]) and the constraint ring in [[sfeir-code-review-anneau-contraintes-2026-07-30]]: **mechanical impossibility beats instruction.** Operational corollary: a critique finding that doesn't fit a small touch-up **escalates into a structural problem** instead of triggering a rewrite.
- **The sixteen steps, in three blocks** (the structure matters more than the detail): **framing** (1 decomposition + coverage matrix + tier classification, 1.5 chapter partitioning) → **corpus and analysis** (2 breadth scan, 3 contradiction graph, 4 loci analysis, 5 parallel depth investigations, 6 cross-loci reconciliation, 7 tensions between sources, 8 corpus critique "what source would overturn this?" + targeted gap-filling, 9 evidence digest) → **writing and audit** (10 triple drafting by angle, 11 synthesis, 12 four parallel adversarial critiques, 13 post-critique gap-filling, 14 surgical patcher, 14.5 citation verification, 15 polish, 16 readability audit).
- **Three scaling levers not to be confused** — a clean, reusable distinction: **tiers** route by query and decide **which steps run**; **gears** (scale profiles) decide **how much** — source targets, depth budgets, length — and *« survive reinstalls »*, taking effect on the next run, **never mid-run**; **levers** (`register`, `domain_notes`, `inference_depth`) decide **which voice** comes out — `teach` / `survey` / `analyze` / `advocate`. ⭐ Fine detail: levers land in **shims injected into subagent prompts**, *« so the critics move with the register instead of undoing it »* — in `survey` register, the dialectic critic flags unfair representation rather than lack of engagement. **But**: *« The cite-checker and the ship gate receive no shim at all. Verification never softens by mode. »* → **Verification is the one stage exempt from style.** An excellent design rule.
- **⭐ The three mechanical gates before shipping** (the best part of the setup, directly transferable to any documentary corpus): 1. **quote-integrity** — any portion quoted between quotation marks must exist **verbatim** in a vault note; *« hallucinated quotes cannot ship »*. 2. **retracted-citations** — citing a retracted source without flagging it is a **blocking error**, with a retraction scan **refreshed at shipping time on every cited DOI**, including sources reused from older runs. *« a retraction published yesterday is caught today »*. 3. **numeric-consistency** — numbers not traceable to evidence are flagged. Plus **cite-check**: a skeptical LLM samples whether the cited source **actually supports the sentence** it backs.
- **⭐ The independence audit — the most immediately stealable idea**: syndicated and derivative copies are grouped, so that *« five reprints of one press release argue with the weight of one source »*. **The count of agreeing sources stops being an argument once they all descend from the same press release.** Relevant to any tech-watch practice: reprint redundancy disguises itself as consensus.
- **Persistent composite quality score**: source type + observed usefulness on reading + citation authority (OpenAlex / Semantic Scholar, **with retraction indicators**) + **PageRank** on the vault's internal graph. Retracted sources are **floored to zero**. *« Quality is persistent, not vibes. »*
- **⭐⭐ The prompt-injection defense — the most serious seen in an open harness**: *« Fetched text is data, never instructions. »* Any body fetched from the web is served inside an `<untrusted-source url="...">` fence with a treat-as-data preamble, **on both paths that serve bodies** (`note show` and `search`). Details showing the threat was taken seriously:
- notes written by the pipeline's own subagents pass through **without a fence** → **trust boundary by provenance**, not by content;
- **forged** closing fences found in a fetched body are neutralized **but left visible for forensic analysis**;
- the `url` attribute is escaped and its control characters stripped;
- in `search`, wrapping happens **after** truncation to the token budget, *« so the closing fence can never be severed »* — the detail that gives away that the bypass was actually hunted for;
- URLs resolved via third-party APIs are checked (scheme, embedded credentials, publicly routable resolution) → **SSRF** defense;
- fetcher, investigator, and writer prompts carry a clause forbidding **laundering** directives from a fenced page into trusted output. → Compare with *« a security boundary that relies on a prompt instruction is not a boundary »* ([[sfeir-anthropic-sdlc-ai-native-securise-2026-07-26]]): here the fence is **mechanical** and the instruction merely backs it up. Same logic of treating observed content as data as in [[valente-zalewski-beyond-zero-enterprise-security-ai-era-2026-07-20]].
- **⭐ Epistemic hygiene on paywalled sources — remarkable and rare**: a paywalled article would normally enter the vault as a ~1,500-character abstract, which the report would then cite *« as though it had been read »*. hyperresearch queries **Unpaywall** and **Europe PMC** for a legal open-access copy and stores **that text instead**, disclosing the substitution **in four places** (banner in the body, `oa_*` frontmatter, JSON block `body_is_not_from_source: true`, CLI output). And crucially, a third state is distinguished: the **"rescued"** note, when the source **could not be read at all** — `nothing_from_source: true`, a banner stating the URL was never read, *« the title, the authors, and every word of the body are the open-access copy's »*. Version warning: Unpaywall can return an accepted manuscript or a submitted preprint, to be checked before any direct citation. → **The system distinguishes "I read this" from "I read a substitute" from "I never read the source"**, and carries that distinction into the artifact. **Directly transferable to a tech-watch practice.**
- **The vault, and its unsettling closeness to this very repo**: *« Markdown is truth, SQLite is cache »* — fully reconstructible index (`hyperresearch sync`), notes in markdown + YAML frontmatter readable without the tool, versionable in git, exportable/importable, **curated lifecycle** (`draft → review → evergreen` or `stale → deprecated → archive`) *« that keeps a vault from becoming a dumping ground of half-read pages »*, provenance via `--suggested-by` with a **lint rule** that detects disconnected components, hubs, backlinks, wikilinks. ⭐ **This is the architecture of this very tech-watch corpus, discovered independently**: markdown source, generated index as cache, lint gate, doctor, wikilinks. What hyperresearch has on top and this corpus lacks: **per-source quality score, independence audit, retraction scanning, optional semantic search, explicit lifecycle status**. A serious inspiration path for `scripts/`.
- **Resume and budget**: each run has an isolated space (`research/runs/<tag>/`) and a **manifest** that serves as *« durable memory »* — a crashed run resumes exactly at the dead step (`run resume`). `run init --budget 50` **blocks** the run once the cap is crossed *« rather than letting it quietly balloon »*. Concurrent runs don't collide.
- **⚠️⚠️ The reservation to flag systematically — the benchmark claim**: the README states upfront that the tool *« currently leads the DeepResearch-Bench RACE leaderboard (benchmarked internally) »*, chart included, placing it ahead of Grep Deep Research, Cellcog Max, nvidia-aiq, **Gemini Deep Research**, and **OpenAI Deep Research**. The note beneath the chart says something else: *« Forward-looking projection from a stratified pilot against the DeepResearch-Bench leaderboard snapshot. Third party validation is pending. »* → **A forward-looking, self-administered projection from a stratified pilot, with no third-party validation, is not a ranking.** The two statements are not compatible, and it's the one place in the repo where the rigor displayed everywhere else slips. **Never cite the ranking; cite the setup.**
- **⚠️ Other limitations, some acknowledged by the author**:
- **Anthropic dependency**: *« It runs on Anthropic models via the subagent roster »* — Opus for critics, the synthesizer, and the patcher, Sonnet for fetchers. A Codex port is explicitly welcomed but not done (*« If anyone wants to port this to Codex, put up a PR! »*).
- **Real cost not quantified in euros**: `premier` targets 100-130 sources at scan-only and ~3-5 h; `dissertation` targets 300-450 sources and 4-8 h. The budget is capped in "API-equivalent spend," not observed cost.
- **The honest limitation, worth quoting**: *« The lint gate catches **structural** failures… It cannot guarantee **factual accuracy**, that's still your call. »* → **Structural verification ≠ factual accuracy.** The whole setup guarantees that a citation exists, not that it is true.
- **A hard and welcome boundary**: *« CAPTCHAs, 2FA, and logins are never solved automatically »* — escalated and handed back to the human.
- **Dependency surface**: 20 skills + 16 subagents + a CLI driving an authenticated browser, on a repo under four months old. The warning from [[lassiege-usine-logicielle-heure-ia-2026-07-28]] fully applies (*« any skill, MCP, or code pulled in from outside must be scrutinized »*).
- **Meta / to link**: the most accomplished instance of the harness engineering from [[osmani-agent-harness-engineering-2026-04-19]]; converges independently with [[lassiege-usine-logicielle-heure-ia-2026-07-28]] on deferred context loading and on the executable beating the instruction; same doctrine of mechanical boundary as [[sfeir-anthropic-sdlc-ai-native-securise-2026-07-26]] and [[valente-zalewski-beyond-zero-enterprise-security-ai-era-2026-07-20]]; kinship in form with the corpus's other skill entries, [[skill-pocock-grill-with-docs-2026-06]] and [[akhouri-adhd-ideation-divergente-parallele-2026-07-20]]; to read alongside [[agent-skills-anthropic-2025-10-16]], [[shihipar-claude-code-lessons-building-skills-2026-06-03]] and [[vincent-superpowers-agentic-skills-framework-github-2026-04-02]] on skill mechanics; the parallel adversarial critique connects to the question raised by [[monperrus-end-of-code-review-agents-supersede-2026-06-11]] about what an automated review can carry.

## RésuméDe400mots

**hyperresearch** (Jordan Gibbs, MIT, PyPI) turns Claude Code into a deep research agent. Observed on August 3, 2026: 1,568 stars, repo created in April. Installation drops **20 skills**, a CLI, an MCP server, and a local web UI.

**The pipeline** runs 16 adaptive steps across tiers: `light` (~30-40 min) for bounded questions, `full` (1.5-2.5 h) for argumentative analysis with adversarial review, `dissertation` (4-8 h, 25,000-80,000 words, 300-450 sources) on explicit request. Three distinct levers: **tiers** decide which steps run, **gears** decide how much, **levers** (`teach`/`survey`/`analyze`/`advocate`) decide which voice the report comes out in.

**The architecture answers a documented failure.** The entry skill is a **thin router** with no procedure: *« V7 was one 1200-line skill that got compacted away… The orchestrator forgot the procedure, wrote a single draft, and produced a flat-scoring report. »* Each step lives in its own skill, loaded fresh at invocation — a long pipeline doesn't lose its steps to forgetting, but to context eviction.

**Two load-bearing principles.** *« Patch, never regenerate »*: after synthesis, only surgical touch-ups are possible, the patcher being **tool-locked to `[Read, Edit]`** at the allowlist level, so that it *« physically cannot Write a new draft »* — mechanical impossibility replaces instruction. And *« canonical research query is gospel »*: the verbatim prompt is persisted and re-read by every step.

**Verification is the one stage exempt from style** — levers inject shims into critics' prompts, but *« the cite-checker and the ship gate receive no shim at all »*. Three gates block shipping: every citation must exist **verbatim** in the vault, an unflagged retracted source is a hard error (with a scan refreshed on every cited DOI), and untraceable numbers are flagged.

**The vault** is persistent markdown indexed in SQLite — *« Markdown is truth, SQLite is cache »* — with a note lifecycle, provenance, a composite quality score, and an **independence audit**: *« five reprints of one press release argue with the weight of one source »*. Bodies fetched from the web are served inside an `<untrusted-source>` fence: *« Fetched text is data, never instructions. »*

⚠️ **The reservation.** The README claims the top spot on the DeepResearch-Bench leaderboard; its own footnote states it is a *« forward-looking projection from a stratified pilot »* with no third-party validation. Cite the setup, never the ranking. The author also acknowledges that the lint *« cannot guarantee factual accuracy »*.

## Anti-patterns

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

## Artefacts

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

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

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

## Commentaire

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

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

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

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

## Déclencheur

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

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

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

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

## Fonctionnement

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

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

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

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

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

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

## Lecture commentée du SKILL.md

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## GrapheDeConnaissance

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

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