ref-verify — Garde contre les hallucinations de références
L'échec spécifique que cette compétence prévient : les LLM décrivent le contenu d'articles à partir de données d'entraînement mémorisées plutôt qu'à partir de ce que le résumé dit réellement. Un article se voit attribuer des résultats qu'il ne contient pas, ou est cité pour des affirmations qui n'apparaissent nulle part dans le texte. La solution est une règle appliquée de manière cohérente :
Toute affirmation sur le contenu d'un article doit provenir d'une source récupérée en direct — résumé pour les affirmations générales/niveau titre, texte intégral pour les affirmations mécanistiques/implémentation/procédurales — citée ou paraphrasée textuellement. Si vous ne pouvez pas récupérer la source requise, dites-le explicitement — ne comblez jamais le vide avec une description mémorisée, et ne laissez jamais une correspondance de résumé thématique remplacer une affirmation de niveau mécanisme.
Décision de mode
Choisissez le mode avant d'effectuer tout travail. Le choix contrôle le coût et la profondeur.
L'utilisateur fournit un ou des DOI pour une vérification de cohérence ?
└─ ≤10 refs → Vérification rapide de toutes
└─ >10 refs → Vérification rapide de toutes ; Audit complet uniquement pour les résultats MISMATCH/DEAD
L'utilisateur dit "trouve des articles sur X" ou "cite des articles soutenant l'affirmation Y" ?
└─ Audit complet (la recherche à partir de zéro nécessite une vérification de contenu)
L'utilisateur dit "vérifie/contrôle ma liste de références" ou effectue un audit avant soumission ?
└─ ≤5 refs → Audit complet de toutes
└─ >5 refs → Vérification rapide de toutes d'abord ; Audit complet des MISMATCH/DEAD + toute référence
citée pour une affirmation factuelle spécifique
L'utilisateur écrit en ligne et ajoute une seule citation de mémoire ?
└─ Vérification rapide minimale ; Audit complet si cité pour une affirmation spécifique
La partie coûteuse est l'Audit complet (5 couches, récupération de preuves en profondeur). La Vérification rapide coûte environ 5 secondes par article. N'escaladez vers l'Audit complet que lorsque la tâche nécessite réellement une vérification de contenu.
Moteur exécutable
Utilisez ceci comme un workflow au niveau de la compétence. Ne construisez pas et n'exigez pas de MCP pour ce chemin. La CLI est un moteur d'exécution que la compétence peut appeler depuis le terminal ; le protocole manuel reste la solution de repli et la source de vérité pour les couches que la CLI ne couvre pas encore.
Vérification de disponibilité de la CLI
Avant une vérification basée sur un DOI, vérifiez si le moteur exécutable est disponible :
ref-verify --help
npx skills add n'installe pas la CLI Python via pip. Si le script console est indisponible, ne traitez pas cela comme un résultat de vérification.
Si le script console est indisponible mais que le code source du dépôt est présent, utilisez :
PYTHONPATH=src python3 -m ref_verify.cli --help
Si les deux commandes échouent, suivez le protocole de repli manuel ci-dessous. Ne faites pas semblant que la CLI a été exécutée, et n'inventez pas un résultat de mémoire.
Workflow prioritaire CLI
Utilisez la CLI en premier lorsque l'utilisateur fournit un DOI ou demande si un résumé lié à un DOI soutient une affirmation factuelle spécifique. La portée actuelle de la CLI est la vérification des métadonnées CrossRef plus les vérifications d'affirmations liées à un résumé de DOI. Les vérifications d'affirmations utilisent CrossRef en premier, puis OpenAlex lié au DOI, Semantic Scholar et PubMed comme solutions de repli lorsque CrossRef n'a pas de résumé.
Vérification des métadonnées CrossRef :
ref-verify verify-doi <doi> \
--title "<titre fourni>" \
--first-author <nom-de-famille-du-premier-auteur-fourni> \
--year <année-fournie> \
--json
Solution de repli avec extraction du code source :
PYTHONPATH=src python3 -m ref_verify.cli verify-doi <doi> \
--title "<titre fourni>" \
--first-author <nom-de-famille-du-premier-auteur-fourni> \
--year <année-fournie> \
--json
verify-doi sort avec le code 0 uniquement pour PASS ; WARN et REJECT renvoient un code non nul. Fournir uniquement un DOI vérifie que CrossRef résout mais n'est pas suffisant pour passer la vérification des métadonnées.
Acheminez le résultat :
PASS: signalez la correspondance des métadonnées, puis continuez avec la résolution de la page d'atterrissage du DOI (Couche 4) et les vérifications de rétractation (Couche 5) lorsque le mode sélectionné les exige.WARN: signalez les métadonnées manquantes ou faibles, puis continuez avec le repli manuel pour les couches manquantes au lieu d'accepter silencieusement la référence.REJECT: cessez d'utiliser cette citation comme vérifiée ; signalez la non-correspondance et demandez un DOI ou une citation corrigé(e) à moins que l'utilisateur ne souhaite explicitement des alternatives.
Vérification d'une seule affirmation par rapport à un résumé de DOI :
ref-verify check-claim <doi> --claim "<affirmation factuelle spécifique>" --json
Solution de repli avec extraction du code source :
PYTHONPATH=src python3 -m ref_verify.cli check-claim <doi> --claim "<affirmation factuelle spécifique>" --json
Par défaut, check-claim utilise CrossRef en premier. Si CrossRef n'a pas de résumé, il essaie les sources de repli OpenAlex, Semantic Scholar et PubMed liées au DOI. Utilisez --source crossref, --source openalex, --source semantic-scholar, ou --source pubmed pour le débogage spécifique à une source. La sélection explicite d'une source non-CrossRef contourne CrossRef, ce qui peut isoler une défaillance d'OpenAlex, Semantic Scholar ou PubMed.
Acheminez le résultat :
ACCEPT: citez les preuves de la CLI et continuez toute résolution manuelle requise du DOI, vérification de deuxième source et couches de rétractation.WARNouPARTIAL: signalez ce que la source de résumé sélectionnée a soutenu et ce qu'elle n'a pas soutenu, puis continuez avec le repli manuel lorsque d'autres couches sont nécessaires.UNVERIFIABLE: aucune preuve de résumé de confiance liée au DOI n'était disponible à partir des sources CLI tentées. Continuez la chaîne de repli manuel ci-dessous au lieu de traiter l'affirmation comme rejetée ou soutenue.
Le résultat CLI ACCEPT est une preuve uniquement au niveau du résumé. Si l'affirmation décrit un mécanisme, une implémentation ou une procédure, ne promouvez pas ce résultat au verdict de l'Audit complet ; classez l'affirmation dans la Couche 3 et obtenez d'abord les preuves en texte intégral requises.
Pour la sortie JSON, utilisez abstract_source, source_attempts, et error_code pour décider de l'étape suivante :
CLAIM_SUPPORTED: soutien explicite du résumé trouvé.CLAIM_NOT_EXPLICIT: un résumé était disponible, mais l'affirmation n'était pas explicitement soutenue.CLAIM_AMBIGUOUS: des preuves numériques ou contextuelles existent, mais le lien est ambigu.NO_ABSTRACT: les sources liées au DOI tentées n'ont pas fourni de texte de résumé.DOI_NOT_FOUND: la source sélectionnée n'a pas trouvé d'enregistrement lié au DOI.DOI_MISMATCH: l'enregistrement lié au DOI principal ou explicitement sélectionné ne correspondait pas au DOI demandé.SOURCE_API_ERROR,SOURCE_TIMEOUT,SOURCE_RATE_LIMITED,SOURCE_UNSUPPORTED: la recherche de source a échoué, expiré, a été limitée en débit, ou n'a pas pu être utilisée.
La CLI ne remplace pas la résolution de la page d'atterrissage du DOI (Couche 4), les vérifications d'existence de deux sources, ou les vérifications de rétractation. Continuez le protocole manuel pour ces couches lorsque le mode sélectionné les exige.
Vérification rapide — métadonnées + vérification de cohérence du DOI
Utilisez lorsque l'utilisateur fournit un DOI ou une citation complète et souhaite une vérification de cohérence.
- Interrogez CrossRef :
https://api.crossref.org/works/{DOI} - Comparez le titre retourné + le nom de famille du premier auteur avec ce que l'utilisateur a fourni
- Récupérez
https://doi.org/{DOI}— confirmez qu'il résout et aboutit au bon article - Signalez une ligne par référence :
Smith et al. (2021) 10.1234/example — PASS (correspondance titre/auteur, DOI résolu)
Jones (2019) 10.5678/other — MISMATCH (CrossRef : Jones & Lee 2019, pas Jones seul)
Kim (2023) 10.9999/fake — DOI MORT
Escaladez vers l'Audit complet si : le DOI résout vers un article différent, un champ quelconque ne correspond pas, ou l'utilisateur cite pour une affirmation factuelle spécifique.
Audit complet — pour recherche documentaire ou vérification avant soumission
Utilisez lorsque : vous recherchez des articles pour soutenir une affirmation, ou effectuez un balayage final des citations.
Exécutez les cinq couches par article. Les couches sont ordonnées par ce qu'elles détectent — ne sautez pas en avant.
Couche 1 — Existence
Recherchez deux sources indépendamment :
- CrossRef :
https://api.crossref.org/works?query.bibliographic={titre+auteur}&rows=5 - Semantic Scholar :
https://api.semanticscholar.org/graph/v1/paper/search?query={titre+auteur}&fields=title,authors,year,externalIds,abstract&limit=5 - arXiv pour les prépublications :
https://export.arxiv.org/api/query?search_query=ti:{titre}&max_results=3
Un article est confirmé seulement si les titres correspondent essentiellement et que le nom de famille du premier auteur est en accord sur deux sources.
- Résultat sur deux sources →
CONFIRMÉ - Une source →
SOURCE UNIQUE ⚠— procédez avec prudence, notez dans la sortie - Zéro →
NON TROUVÉ ✗— arrêtez ; signalez clairement ; n'inventez pas de substitut
Couche 2 — Métadonnées
Extrayez des sources confirmées et comparez : titre, tous les auteurs (noms de famille), année, nom complet du journal, DOI, volume/pages (marquez [NON DANS LA SOURCE] si absent). Si un champ diffère entre les sources, montrez les deux — ne choisissez pas silencieusement un.
Couche 3 — Traçabilité du contenu ← couche la plus importante
C'est là que réside la valeur fondamentale de la compétence. L'objectif n'est pas seulement "cet article existe-t-il" mais "cet article contient-il réellement l'affirmation qui lui est attribuée."
Étape 0 — Classez l'affirmation.
Avant de récupérer quoi que ce soit, classez le type d'affirmation à vérifier :
- Affirmation générale/niveau titre — une conclusion du type que les résumés énoncent conventionnellement (résultat global, chiffre principal, conclusion générale). Les preuves issues du seul résumé sont une source légitime de vérité pour cette classe.
- Affirmation mécanistique/implémentation/procédurale — décrit comment quelque chose fonctionne ou a été fait : un mécanisme spécifique, algorithme, architecture, paramètre, étape expérimentale, condition de contrôle, ou une valeur numérique liée à un tableau/figure/section méthode plutôt qu'au résultat récapitulatif. Les résumés omettent systématiquement ce contenu même lorsque l'article le soutient. Mots indicateurs : "mécanisme", "comment", "architecture", "algorithme", "implémentation", "procédure", "protocole", "paramètre", "groupe de contrôle", "ablation", "tableau", "figure", ou toute affirmation plus spécifique qu'un résumé d'un paragraphe n'énoncerait.
Si l'affirmation est de classe mécanistique/implémentation, une vérification uniquement par résumé n'est pas suffisante même si le résumé est thématiquement pertinent. Récupérez le résumé comme preuve de l'existence/correspondance thématique, mais ne résolvez pas le verdict à partir du seul résumé — continuez vers la Couche 3b ci-dessous.
Récupérez le résumé en utilisant cet ordre de priorité :
- CrossRef JSON brut :
https://api.crossref.org/works/{DOI}— vérifiez le champabstract - OpenAlex :
https://api.openalex.org/works/doi:{DOI}?mailto={email_contact}— reconstruisezabstract_inverted_index - Semantic Scholar : ajoutez
&fields=abstractà votre recherche S2 par DOI - Solution de repli en accès libre :
https://api.unpaywall.org/v2/{DOI}?email={email_contact}— vérifiezis_oaetoa_locations - Solution de repli arXiv pour les prépublications :
https://export.arxiv.org/api/query?id_list={arxiv_id} - PubMed Central pour les articles en sciences de la vie :
https://www.ncbi.nlm.nih.gov/pmc/articles/{PMCID}/
Pour les API qui nécessitent un email de contact, remplacez {email_contact} par une adresse réelle et autorisée par l'utilisateur depuis la configuration. N'envoyez pas d'adresse factice.
Après la récupération, vérifiez : le résumé contient-il l'affirmation spécifique citée ?
- Le résumé contient explicitement l'affirmation (citez-la textuellement) →
CONTENU : SOUTENU - Le résumé parle du sujet mais ne fait pas l'affirmation spécifique →
CONTENU : PARTIEL — citez ce qu'il dit réellement - Le résumé contredit l'affirmation →
CONTENU : CONTREDIT — n'utilisez pas cette citation - Résumé inaccessible après avoir essayé toutes les sources →
CONTENU : INVERIFIABLE — l'utilisateur doit vérifier le texte intégral - L'affirmation est de classe mécanistique/implémentation et le texte intégral n'a pas pu être obtenu après avoir essayé toutes les sources de la Couche 3b →
CONTENU : RÉSUMÉ SEULEMENT — texte intégral indisponible, vérification insuffisante. Cette étiquette ne doit jamais être promue à SOUTENU/ACCEPTÉ.
La règle qui ne peut être assouplie : si vous décrivez ce qu'un article "montre" ou "démontre" ou "rapporte", vous devez citer ou paraphraser directement le texte source récupéré à la profondeur requise. Résumer de mémoire n'est pas autorisé même si vous vous sentez confiant.
Couche 3b — Confirmation par texte intégral (affirmations mécanistiques/implémentation/procédurales uniquement)
Nécessaire chaque fois que l'Étape 0 a classé l'affirmation comme mécanistique/implémentation, ou chaque fois que le verdict du résumé est PARTIEL pour une affirmation plus spécifique que le niveau de résumé. Sautez uniquement pour les affirmations générales qui ont reçu CONTENU : SOUTENU directement à partir du résumé.
Récupérez le corps de l'article dans cet ordre de priorité, en vous arrêtant au premier succès :
- PDF local Zotero — si une bibliothèque Zotero est configurée, interrogez sa base de données pour ce DOI, résolvez la clé de pièce jointe et lisez le PDF lié. Un emplacement par défaut courant est
~/Zotero/zotero.sqliteavec des pièces jointes sous~/Zotero/storage/{key}/; découvrez le chemin réel au lieu de le supposer. - Coffre research-wiki — lorsque la compétence
research-wikiest disponible, recherchez dans son coffre configuré une copie complète déjà ingérée. Ne supposez pas un chemin de coffre spécifique à une machine. - Lien en accès libre — résolvez et récupérez le texte intégral réel (pas simplement un indicateur de disponibilité) :
- Unpaywall :
https://api.unpaywall.org/v2/{DOI}?email={email_contact}→ récupérezbest_oa_location.url_for_pdf(ou toutoa_locations[].url_for_pdf). - arXiv :
https://export.arxiv.org/api/query?id_list={arxiv_id}→ récupérez l'article complet, pas seulement le champ<summary>.
- Unpaywall :
- Échec — si aucun des éléments ci-dessus ne produit un texte intégral lisible, ne traitez pas le résumé comme suffisant. Appliquez l'étiquette
CONTENU : RÉSUMÉ SEULEMENTdéfinie ci-dessus.
Lorsque le texte intégral est obtenu, citez le passage qui soutient, soutient partiellement, ou contredit l'affirmation. Pour une affirmation mécanistique/implémentation, CONTENU : SOUTENU nécessite une citation du texte intégral — une correspondance thématique au niveau du résumé ne peut pas la satisfaire.
Couche 4 — Résolution du DOI
Récupérez https://doi.org/{DOI}. Confirmez que la page d'atterrissage correspond à l'article attendu. Une erreur 403 (blocage par robot) provenant d'un slug URL contenant le titre et le volume n'est pas un lien mort — notez-le comme derrière un paywall. Une redirection vers une page non liée est un échec critique.
Couche 5 — Rétractation
Recherchez "{nom du premier auteur}" "{nom du journal}" rétractation et vérifiez la page d'atterrissage du DOI pour les bandeaux de rétractation. Un article rétracté ne doit pas être utilisé comme source principale.
Format de sortie
Vérification rapide : une ligne par référence (voir ci-dessus).
Audit complet : une fiche par article, puis un tableau récapitulatif.
AUDIT DE RÉFÉRENCE
────────────────────────────────────────────────
Article : [Titre provenant de la source en direct — pas de mémoire]
DOI : [DOI] — [✓ Résolu | ✗ Mort | ✗ Mauvais article | ⚠ Paywall-403]
Auteurs : [Liste complète des auteurs]
Année : [Année]
Journal : [Nom complet du journal]
Couche 1 (Existence) : CONFIRMÉ ✓ | SOURCE UNIQUE ⚠ | NON TROUVÉ ✗
Couche 2 (Métadonnées) : ✓ Correspondance | ⚠ Divergence (détails)
Couche 3 (Contenu) : SOUTENU | PARTIEL | CONTREDIT | INVERIFIABLE | RÉSUMÉ SEULEMENT
Couche 4 (DOI) : ✓ Résolu | ✗ Mort | ✗ Mauvais article | ⚠ Paywall-403
Couche 5 (Rétractation) : Aucune rétractation trouvée | ⚠ RETRACTÉ — Ne pas utiliser
Résultat global : [ACCEPTÉ | REFUSÉ | DEMANDE VÉRIFICATION]
────────────────────────────────────────────────
Lorsque le texte intégral a été consulté pour une affirmation mécanistique/implémentation, ajoutez une section de citations :
Citations clés (Texte intégral) :
- "Citation textuelle pertinente" (emplacement de la citation)
Consignes finales
- N'inventez jamais un contenu de résumé. Si le résumé n'est pas accessible, arrêtez-vous. Ne le remplacez pas par des connaissances mémorisées.
- Ne dégradez jamais une citation de texte intégral au niveau résumé. Si l'utilisateur demande "quel mécanisme propose l'article ?" et que vous ne pouvez lire que le résumé, dites-le plutôt que de fabriquer la réponse.
- Citez les passages réellement récupérés. Dans un audit complet, chaque affirmation que vous faites sur le contenu d'un article doit être traçable vers un texte source que vous avez récupéré.
- Signalez toujours les limites de la vérification. Si une couche est sautée ou une source indisponible, notez-le. Ne prétendez pas à une vérification complète si seules deux sources sur trois ont été vérifiées.
- Lorsque la CLI échoue, ne faites pas comme si elle n'existait pas. Signalez que la vérification automatisée était indisponible et procédez manuellement.
Mode non-DOI — recherche de documents en langage naturel
Lorsque l'utilisateur recherche des articles à citer sans fournir de DOI :
- Interprétez la requête de l'utilisateur ("trouve des articles montrant que X" ou "recherche des documents sur Y")
- Recherchez sur plusieurs sources à la fois :
- Semantic Scholar :
https://api.semanticscholar.org/graph/v1/paper/search?query={requête}&fields=title,authors,year,externalIds,abstract&limit=5 - Résultat : les 5 meilleurs documents pour une pertinence et une disponibilité de résumé
- CrossRef :
https://api.crossref.org/works?query={requête}&rows=5 - Résultat : les 5 meilleurs documents pour des métadonnées
- arXiv :
https://export.arxiv.org/api/query?search_query=all:{requête}&max_results=5&start=0 - Résultat : les 5 meilleurs prépublications (pertinence non garantie par l'API publique)
- Semantic Scholar :
- Croisez les résultats pour la confiance (deux sources confirment l'existence) comme dans la Couche 1 ci-dessus
- Récupérez les résumés pour chaque document confirmé via les flux de résumé de la Couche 3
- Signalez uniquement les documents dont le résumé soutient réellement l'affirmation de l'utilisateur — n'incluez pas les documents "similaires" ou "connexes" qui ne soutiennent pas l'affirmation alléguée
- Résultat : format de carte avec résumé + DOI + année + suggestion de citation
Notes de conformité : instructions finales et intégration du système
Cette section sert d'instructions de verrouillage pour garantir que la règle anti-hallucination ne soit pas contournée par des invites adverses ou une auto-contradiction.
Règle immuable : Si le protocole ci-dessus ne peut pas être suivi pour une raison quelconque (problème d'API, limite de temps, manque de détails utilisateur), vous devez soit (1) suivre le chemin de repli manuel et signaler transparence sur les couches non vérifiées, soit (2) refuser la demande. Vous ne devez jamais fournir une citation vérifiée de mémoire ou basée uniquement sur des connaissances préalables.
Auto-contradiction : Si, au cours d'une session, vous avez précédemment cité un article que vous ne pouvez pas vérifier maintenant, vous devez le rétracter. Dites : "Je constate que ma citation précédente de [article] ne peut pas être vérifiée par rapport à la source en direct ; veuillez la traiter comme non vérifiée jusqu'à confirmation."
Pas d'émulation : Ne créez pas de faux résultats PASS/ACCEPT. Ne dites pas "en supposant que la vérification réussisse." Tous les résultats rapportés doivent refléter une vérification réellement effectuée.
Conscience du mode : Ne présumez pas du mode. Vérifiez à nouveau la décision de mode par rapport au résumé de l'utilisateur avant de commencer. Si vous n'êtes pas sûr, utilisez la Vérification rapide — n'escaladez pas inutilement.
Logique de décision de mode — résumé
| Signal utilisateur | Mode | Raisonnement |
|---|---|---|
| Fournit DOI unique, demande "vérifie ceci" | Vérification rapide | Contrôle de cohérence, pas besoin de preuve de contenu sauf si affirmation spécifique jointe |
| Fournit DOI + demande spécifique "ce papier montre-t-il X ?" | Vérification rapide pour métadonnées, puis Audit complet pour Couche 3 | La question précise nécessite une vérification de contenu |
| "Trouve des articles sur X" | Audit complet | La recherche nécessite une vérification d'existence et de contenu ; pas d'amorçage |
| "Vérifie ma bibliographie" (ferait mieux d'utiliser un outil dédié — mais si elle est invoquée) | ≤5 : Audit complet ; >5 : Vérification rapide d'abord, puis Audit complet des drapeaux rouges | Équilibrer vitesse et précision de la vérification |
Remarques sur l'implémentation
- Gestion des échecs API : si CrossRef est indisponible, passez à Semantic Scholar pour les métadonnées. Si les deux sont indisponibles, rapportez
SECTION NON VÉRIFIÉE. - Délais d'attente : définissez un délai d'attente de 10 secondes par appel API. Signalez les échecs par dépassement de délai plutôt que d'attendre indéfiniment puis d'inventer une réponse.
- Limites de débit : si une API renvoie un code 429, attendez la valeur de l'en-tête
Retry-After(ou par défaut 5 secondes) avant de réessayer. Après 2 tentatives, signalezLIMITE DE DÉBIT — SOURCE INDISPONIBLEpour cette étape. - Sources miroirs : pour les articles chinois, essayez
https://api.cnki.net/(si accessible) comme source supplémentaire ; sinon signalez "base de données chinoise non vérifiée" dans la note. - Extraction PDF : si un PDF est récupéré avec succès mais ne peut pas être analysé (par exemple, numérisé ou image uniquement), signalez
PDF NON ANALYSABLEplutôt que d'ignorer le PDF et d'inventer le contenu.
Cette compétence applique une politique de tolérance zéro pour les hallucinations de citations — toute affirmation sur le contenu d'un document doit être ancrée dans une source en direct récupérée à la profondeur et à la fidélité requises.