danepps/compétences-recherche-juridique

Construire une bibliothèque

Peupler une collection Zotero avec des sources pour un projet. Double protection contre les sources fabriquées : (1) vérifier chaque candidat auprès d'une source réelle avant de l'ajouter ; (2) après l'ajout, exécuter le vérificateur déterministe intégré — aucun élément n'est livré non vérifié. Toutes les règles d'autorité globales (ne jamais inventer une citation ; signaler l'incertitude) s'appliquent tout au long du processus.

0. Étape zéro — lisez l'intégralité de la bibliothèque avant toute autre action

Avant de cadrer, avant de rechercher, avant de proposer un seul candidat, déchargez la bibliothèque cible et lisez-la entièrement :

python3 ${CLAUDE_PLUGIN_ROOT}/skills/build-library/library_inventory.py --group <ID>   # ou --user
python3 ${CLAUDE_PLUGIN_ROOT}/skills/build-library/library_inventory.py --group <ID> --grep <termes>

Une ligne par élément de premier niveau : année, PDF ou non, auteurs, titre, publication, clé d'élément. Une bibliothèque de 100 éléments représente bien moins de 3k tokens. Il n'y a aucune raison budgétaire de sauter cette étape et rien ne la remplace. Pour une grande bibliothèque (des milliers d'éléments), enregistrez le déchargement complet dans un fichier et lisez les tranches --grep pertinentes ainsi que la forme générale — mais le coordinateur reste propriétaire de la vérification, et une tranche qui n'a jamais été interrogée par grep n'est pas une preuve d'absence.

Il s'agit de l'étape zéro plutôt que d'une partie de l'écran de dédoublonnage car connaître la bibliothèque change ce que vous allez chercher. Une exécution qui saute cette étape proposera des choses que l'utilisateur possède déjà, les décrira comme « nouvellement identifiées » et fera de fausses déclarations sur les lacunes de la collection.

Quatre règles strictes, chacune issue d'un échec réel (2026-08-01, sur une bibliothèque de groupe de 105 éléments) :

1. Ne déléguez jamais l'inventaire ou la vérification de dédoublonnage à un sous-agent. Un sous-agent de recherche a signalé que le groupe contenait « seulement les 13 éléments listés plus une poignée d'œuvres sans rapport ». Il en contenait 105. Le coordinateur l'a cru et a créé trois doublons. Les sous-agents sont acceptables pour trouver des candidats ; le coordinateur est propriétaire de la connaissance de la bibliothèque.
2. Considérez une conclusion négative d'un sous-agent comme non vérifiée. « J'ai vérifié et ce n'est pas là » est exactement l'affirmation que les sous-agents se trompent, car l'absence n'est pas falsifiable depuis une recherche étroite. Revérifiez toute affirmation « pas dans la bibliothèque » par rapport à votre propre inventaire.
3. Chaque ajout passe par la vérification, y compris les ajouts tardifs. Deux des trois doublons ont été ajoutés à la toute fin de la session, à partir de notes de bas de page dans un article qui venait d'être lu — en dehors du pipeline principal, ils ont donc complètement sauté l'écran. Aucun candidat n'est trop petit ou trop tardif pour être vérifié ; interrogez l'inventaire que vous possédez déjà.
4. Transmettez l'inventaire. Tout sous-agent chargé de trouver des sources reçoit la liste réelle (ou une tranche filtrée) collée dans son invite — jamais une instruction pour aller vérifier lui-même.

La bibliothèque est aussi une preuve. Lorsque la tâche est « qu'est-ce qui manque », ce que l'utilisateur possède déjà vous indique ce qui l'intéresse et reformule souvent la réponse. Dans l'exécution qui a motivé cette règle, la bibliothèque de l'utilisateur s'est avérée contenir une étagère profonde de recherche en droit pénal exactement sur les sujets que la note venait de décrire comme non traités — ce qui a changé la conclusion de « personne n'a écrit sur ce sujet » à « ces deux littératures ne se citent pas mutuellement ». Lisez l'inventaire pour ce qu'il dit sur le projet, pas seulement pour la correspondance des doublons.

1. Plomberie Zotero

Les outils MCP zotero / zotero-group sont en lecture seule (utiles pour les vérifications de doublons et la recherche). Toutes les écritures passent par l'API Web Zotero v3 avec la clé de l'entrée zotero dans ~/.claude.json (env.ZOTERO_API_KEY ; vérifié pour avoir un accès en écriture à la bibliothèque personnelle, <ID_UTILISATEUR>, et à toutes les bibliothèques de groupe que vous utilisez).

• Collections : GET /users/<ID_UTILISATEUR>/collections?limit=100 → trouver la clé cible ; créer avec POST /collections si l'utilisateur souhaite une nouvelle collection (confirmer le nom d'abord).
• Vérification des doublons — inventaire d'abord (§0), filtrer la liste des candidats (§2a), filet de sécurité avant l'ajout : lire l'intégralité de la bibliothèque au préalable (§0) ; dédoublonner la liste des candidats avant toute vérification ou travail sur les PDF (§2a) ; puis effectuer une vérification finale légère juste avant le POST /items comme filet de sécurité — elle détecte les éléments ajoutés plus tôt dans la même exécution et les collisions d'édition exacte que les écrans précédents manquent. Pour des recherches ponctuelles en cours d'exécution, library_inventory.py --grep <termes> surpasse mcp__zotero__zotero_search_items, car il recherche dans la liste que vous possédez déjà plutôt que d'émettre une nouvelle requête étroite.
• Créer des éléments : POST /users/<ID_UTILISATEUR>/items avec un tableau JSON (≤50/requête). Vérifier les cartes success/failed de la réponse. Obtenir un modèle vierge à partir de GET https://api.zotero.org/items/new?itemType=book en cas de doute sur les champs.
• Conventions : illustrateurs/mentions « avec » → créateurs contributor plus une note extra (les livres Zotero n'ont pas de rôle illustrateur) ; éditeurs → editor ; mettre le véritable éditeur/imprimeur de l'édition (par exemple Sentinel, pas « Penguin ») ; date de publication complète lorsqu'elle est vérifiée, année sinon ; ISBN toujours pour les livres, DOI toujours pour les articles.

1a. Métadonnées des articles de revues juridiques — corrections pour les défauts du connecteur Zotero (auteur, 2026-07-16)

Claude crée des éléments via l'API Web, il peut donc les obtenir correctement là où le connecteur Zotero de l'utilisateur les obtient systématiquement de manière erronée. Appliquer à chaque article de revue juridique ajouté ; Hein (§4a) affiche les données correctes, prenez donc les champs de là.

1. « Le »/« La »/« Un »/« Une » en tête : garder l'article en position naturelle — titre The Common Law, jamais le Common Law, The inversé pour le tri du connecteur.
2. Année = l'année du numéro, pas la plage du volume. Le connecteur prend souvent la plage de dates du volume entier ; utilisez l'année du numéro spécifique, que la citation Hein donne.
3. Point d'interrogation final : le conserver — Are Judges Political?, pas Are Judges Political.
4. Italiques dans les titres : le champ titre de Zotero accepte le HTML en ligne — encadrez les noms de cas (et autres termes en italique selon le Bluebook) avec <i>…</i>, par exemple The Real Meaning of <i>Erie</i> ou Rethinking <i>Chevron</i> Deference. Zotero les rend et les exporte en italique (c'est le <i>nom du cas</i> que l'utilisateur ajoute autrement à la main).
5. Supprimer les étiquettes de type de pièce / symposium ajoutées au titre — mais conserver les désignations Bluebook réelles dans extra. Le connecteur ajoute des désignations au titre — Essay, Comment, Note, Foreword, Book Review, Symposium: <nom>, etc. Ne conservez que le titre réel de l'article tel qu'il apparaît en tête de la pièce / dans la citation Bluebook. En cas de doute sur le fait que le texte final soit un véritable sous-titre ou une étiquette ajoutée, vérifiez la première page.
   • Notes et commentaires étudiants (et autres désignations que le Bluebook imprime entre l'auteur et le titre — Recent Development, Essay, Foreword, Book Review, etc.) : ne vous contentez pas de supprimer l'étiquette. Enregistrez-la dans le champ extra de l'élément sous forme de ligne genre: — genre: Note pour une note étudiante, genre: Comment pour un commentaire (en majuscule de titre ; le style le met en majuscule de titre quoi qu'il arrive, mais stockez-le proprement). Le style Bluebook l'insère alors au bon endroit (Jane Doe, Note, <i>Titre</i>, 120 Harv. L. Rev. 1627 (2007)). Supprimez-le du titre comme ci-dessus et ajoutez la ligne genre: — les deux vont de pair pour ces pièces.
   • Notes étudiantes anonymes (aucun auteur listé) : laissez les créateurs vides et définissez toujours genre: Note. Si le champ extra contient déjà d'autres lignes (par exemple Verified-URL:), ajoutez genre: Note sur sa propre nouvelle ligne — ne les écrasez pas.
6. Suffixes (« Jr. », « III », « Sr. ») : Zotero n'a pas de champ suffixe — encodez le suffixe dans le champ Prénom, ajouté au prénom avec une virgule et sans espace (lastName reste uniquement le nom de famille ; n'ajoutez jamais le suffixe au nom de famille ni n'ajoutez un second auteur). Un ! en tête du suffixe contrôle si une virgule est rendue avant lui (balisage citeproc-js, selon l'auteur) :
   • « John Smith Jr. » (sans virgule) → firstName: "John,Jr.", lastName: "Smith"
   • « John Smith, Jr. » (avec virgule) → firstName: "John,!Jr.", lastName: "Smith" Le prénom incluant tout deuxième prénom/initiale va avant la virgule (par exemple John B.,Jr.). Même mécanisme pour les chiffres/autres suffixes — John,III vs John,!III, John,Sr. etc. Faire correspondre la forme de virgule utilisée par l'auteur/la source.
7. Abrév. revue (Bluebook, casse mixte) : toujours remplir le champ journalAbbreviation de Zotero (« Abrév. revue » dans l'interface) avec l'abréviation Bluebook de la revue (Tableau T13) en casse mixte normale — Colum. L. Rev., Harv. L. Rev., Nw. U. L. Rev., J. Sup. Ct. Hist., Sup. Ct. Rev. — PAS en majuscules. Le style de citation applique lui-même les petites majuscules, stockez donc Colum. L. Rev., jamais COLUM. L. REV. Le nom complet reste dans publicationTitle ; l'abréviation va dans journalAbbreviation. L'affichage de la citation Hein la rend en majuscules/petites majuscules (« 62 COLUM. L. REV. 633 ») — utilisez-la pour le libellé mais convertissez en casse mixte ; pour une revue inconnue, vérifiez la forme T13 plutôt que de deviner. Pour un complément/supplément en ligne, ajoutez le nom du supplément abrégé selon le Bluebook — Forum → F. (par exemple Harv. L. Rev. F.), tandis que Colloquy n'a pas de forme courte (Nw. U. L. Rev. Colloquy). Exceptions connues spécifiques au nom (ne « corrigez » pas celles-ci) : California Law Review → Calif. L. Rev. (pas Cal., même si la Californie est Cal. dans les recueils de jurisprudence et ailleurs). La bizarrerie Calif. est spécifique à cette revue — contrastez avec Southern California Law Review → S. Cal. L. Rev., où la Californie prend le Cal. habituel.

2. Trouver des candidats

Cadrez avec l'utilisateur si la demande est ouverte (quels juges/universitaires/époque ; livres seulement ou articles aussi ; livres commerciaux vs. manuels/traités — signalez les jugements de valeur dans le rapport plutôt que de décider silencieusement). Faites-le après le §0, jamais avant — l'inventaire vous indique ce que l'utilisateur possède déjà, ce qui change ce qui vaut la peine d'être recherché.

Recherchez en parallèle : WebSearch ; Open Library (search.json?title=&author= surpasse le q= nu) ; infobox Wikipédia (/w/index.php?title=<page>&action=raw, cherchez dans l'infobox) pour l'éditeur/date/ISBN des livres notables ; pages des éditeurs. Pour la recherche juridique, HeinOnline (§4). L'API Google Books est un quota anonyme partagé qui est souvent épuisé — traitez-la comme un bonus, pas comme une colonne vertébrale.

2a. Filtrer les candidats par rapport à la bibliothèque

Avec l'inventaire en main, dédoublonnez la liste des candidats avant le pipeline coûteux vérifier → télécharger → ajouter (§3+). La vérification des métadonnées et le téléchargement des PDF (chaînes curl Hein, attach_pdf.py) est la partie coûteuse d'une exécution ; le faire pour une source déjà dans la bibliothèque est un pur gaspillage.

1. Faites correspondre chaque candidat à l'inventaire d'abord sur auteur + année, puis sur titre — les titres varient (sous-titres, « Partie I », articles inversés pour le tri, entités HTML) mais les collisions auteur-plus-année sont un déclencheur fiable pour un examen plus approfondi.
2. Supprimez les correspondances claires (même œuvre déjà présente) — ne les vérifiez ni ne les téléchargez.
3. Signalez, ne supprimez pas silencieusement, les quasi-correspondances ambiguës (même auteur, titre similaire mais pas identique ; une édition/tirage différent ; article vs. son complément en ligne). Vous ne pouvez parfois cerner l'édition exacte que lors de la vérification, alors portez une vraie possibilité et notez-la dans le rapport plutôt que de l'écarter en devinant.

Seuls les survivants passent par le §3. Le filet de sécurité avant ajout du §1 détecte ensuite les doublons intra-exécution et les collisions d'édition exacte.

Si vous créez un doublon, fusionnez avant de supprimer. L'élément préexistant peut contenir le PDF, les annotations, les tags et les appartenances à des collections de l'utilisateur ; votre nouvel élément peut contenir de meilleures métadonnées. PATCH les bons champs sur l'élément existant, puis SUPPRIMEZ le vôtre. Ne supprimez jamais l'enregistrement le plus ancien. (Dans le nettoyage du 2026-08-01, cela a récupéré un vrai défaut : l'élément Kahan de l'utilisateur avait la chaîne « 10.2307 » dans son champ issue et pas de DOI.)

Règle de flux de travail (auteur, 2026-07-16) : résoudre chaque source de revue juridique via HeinOnline. Hein est la voie autonome propre (§4a : authentifié par IP, pas de mur anti-bot, pas de barrière). Une source que Hein ne contient pas et qu'aucun référentiel ouvert ne sert est signalée comme telle (§5) plutôt que d'être ajoutée sans enregistrement vérifié.

3. Vérifier → ajouter → vérification déterministe (non négociable)

Avant d'ajouter : chaque champ que vous écrivez doit provenir d'une source récupérée — un enregistrement d'édition Open Library (/isbn/<isbn>.json), une page d'éditeur, une infobox Wikipédia, une liste de libraire. N'écrivez jamais un ISBN/date/éditeur plausible de mémoire. Méfiez-vous des enregistrements d'édition OL corrompus (un mauvais livre derrière un ISBN arrive) ; recoupez toute surprise avec une deuxième source.

Après l'ajout, exécutez le vérificateur intégré sur exactement ce qui a atterri dans Zotero :

python3 ${CLAUDE_PLUGIN_ROOT}/skills/build-library/check_source.py --collection <CLÉ>   # collection entière
python3 ${CLAUDE_PLUGIN_ROOT}/skills/build-library/check_source.py --keys K1,K2,K3      # juste les nouveaux éléments

Il résout l'ISBN de chaque élément via cinq catalogues indépendants (Open Library édition + index de recherche, Google Books, Harvard Library, Library of Congress) ou son DOI via Crossref, et effectue une comparaison normalisée de chaînes du titre/auteurs/année. Verdicts : PASS, FAIL (résolu mais non correspondant), UNRESOLVED (identifiant non trouvé dans aucun catalogue vérifié — une invitation à revérifier, pas une preuve de fabrication : les catalogues sont incomplets et parfois indisponibles), BAD_ISBN (somme de contrôle), NO_IDENTIFIER. --stdin accepte un tableau JSON d'éléments au format Zotero pour pré-vérifier les candidats avant de les ajouter.

Chaque élément que vous avez ajouté doit finir PASS. Manuel pour les non-PASS :

• FAIL sur une seule source → généralement une corruption de catalogue ; le vérificateur essaie déjà les autres sources, donc un FAIL persistant signifie généralement que vos données sont erronées — revérifiez par rapport à une page faisant autorité ouverte et PATCH l'élément (envoyez If-Unmodified-Since-Version: <version de l'élément>). Si la page ouverte confirme vos données, enregistrez-la comme Verified-URL: et dites-le dans le rapport plutôt que de « corriger » des métadonnées correctes pour correspondre à un catalogue.
• UNRESOLVED/trop récent pour les catalogues (livres < ~1 an) → ajoutez une page faisant autorité récupérable comme

…

[TRONQUÉ POUR TRADUCTION]