MinorBaek/wiki-ingest

Que fait wiki-ingest ?

Implémente le pattern d'ingestion LLM-wiki pour une base de connaissances scientifiques. Chaque article ingéré crée une connaissance traçable et cumulative, pas seulement une note isolée.

Avant la première ingestion, lisez docs/GOTCHAS.md dans le kit (les pièges opérationnels pour l'ingestion, la synthèse et le lint).

Modes

• par défaut (ingestion) : /wiki-ingest <article> crée ou met à jour la fiche de l'article et propage aux concepts et méthodes (Workflow par défaut ci-dessous).
• mode vérification : /wiki-ingest verify:<FicheArticle> revérifie une fiche existante par rapport à son texte intégral et signale les différences sans régénérer ni écraser quoi que ce soit (voir references/VERIFY-DIFF-MODE.md). En lecture seule sauf si l'utilisateur confirme chaque modification.

Rôle et limites

Fait : crée ou met à jour les fiches d'articles, propage aux fiches de concepts et de méthodes, met à jour l'index et le journal, signale chaque changement.

NE fait PAS : n'invente pas de citations, ne crée pas de fiches de concepts pour des concepts à usage unique, n'écrit pas dans une base de données. Toutes les écritures passent par les outils de fichiers de l'hôte (Read/Write/Edit).

Où se trouvent les choses

Les chemins proviennent de wiki.config.json (racine du vault, racine du wiki, noms de dossiers, langue, seuils). Valeurs par défaut :

<vault_root>/
  <wiki_root>/            # par défaut : wiki/
    papers/  concepts/  methods/  books/  fields/  debates/
    WIKI_SCHEMA.md        # contrats frontmatter, nommage, taxonomie, protocole d'ingestion
    index.md  log.md
  templates/              # paper.md, concept.md, method.md, book.md, chapter.md, submoc.md, synthesis.md

<kit> ci-dessous désigne le checkout du science-wiki-kit qui contient tools/ (seal.py, pmc_tables.py). Son chemin est la clé kit_dir de wiki.config.json, écrit par l'installateur ; s'il manque, il se trouve deux dossiers au-dessus du répertoire de ce skill lorsque le skill est lié depuis le checkout.

Lisez toujours WIKI_SCHEMA.md avant de commencer. Il définit les contrats frontmatter, les règles de nommage et la taxonomie de domaine de ce wiki.

Skills associés

• wiki-lint : partage wiki.config.json (la correspondance kebab-case vers Title Case utilisée dans les mises à jour d'index). Exécutez-le après chaque ingestion pour vérifier qu'aucune dérive n'a été introduite.
• wiki-ingest-book : skill compagnon pour les livres et chapitres. Les mêmes règles de statut et de routage d'index s'appliquent.
• wiki-synthesize : consomme les notes produites par ce skill.

Décision de statut initial (appliquée à toute nouvelle note)

Définissez status délibérément. Ne laissez pas la valeur par défaut du modèle. N ci-dessous est min_distinct_sources_for_final dans la configuration (par défaut 2).

Type de note	Condition	status initial
Article	Résumé + au moins 2 résultats sourcés extraits	read
Article	Seulement les métadonnées DOI/titre, pas de texte intégral	stub + > [!warning] Stub : en attente d'ingestion. callout
Concept	Au moins 2 résultats sourcés provenant de N ou plus sources distinctes	final
Concept	Au moins 2 résultats sourcés, tous provenant d'une seule source	draft (synthèse monosource)
Concept	Définition + 1 résultat sourcé	draft
Concept	Définition uniquement, sans Résultats Clés	stub + > [!warning] Stub : pas encore de résultats sourcés. callout
Méthode	Définition + N ou plus sources distinctes sous "Articles Utilisant Cette Méthode"	final
Méthode	Définition et seulement 1 source	draft (monosource)
Méthode	Définition mais aucune citation source	draft
Méthode	Seulement une ébauche	stub

La promotion vers final nécessite N sources DISTINCTES. "Distinct" compte les articles ou livres indépendants : une fiche parent d'un livre et ses propres fiches de chapitres (Auteur_2025 + Auteur_2025_Ch01 + Auteur_2025_Ch02) se réduisent à un seul ouvrage, tout comme plusieurs chapitres du même livre. Une source unique riche (revue systématique, chapitre de manuel) peut créer un concept et produire plusieurs résultats, mais la fiche reste draft jusqu'à ce qu'une deuxième source indépendante la corrobore. Lors de l'ajout d'un résultat à une fiche draft, comptez les œuvres distinctes après la modification, ne promouvez que si le nombre atteint N, et enregistrez la promotion dans le rapport d'ingestion. Les fiches draft monosource portent une brève ligne "synthèse monosource, à corroborer lorsqu'une 2e source est ingérée" dans le corps.

Workflow par défaut

1. Lire le schéma

Lisez WIKI_SCHEMA.md.

2. Résoudre la source de l'article

Essayez dans l'ordre, en utilisant ce que votre environnement fournit :

• Gestionnaire de références (Zotero MCP est l'adaptateur pris en charge) : recherchez, puis métadonnées, puis texte intégral. Séquence et pièges de recherche dans references/INGEST-WORKFLOW.md.
• Tableaux XML de l'éditeur (libre accès dans PMC) : si le DOI a un PMCID, les tableaux peuvent être extraits cellule par cellule depuis Europe PMC JATS, indépendamment de la couche texte du PDF : python <kit>/tools/pmc_tables.py <DOI> --out _temp/<racine>_pmc.md --body (code de sortie 2 signifie pas de PMCID). Vérifiez les numéros de tableaux par rapport au JATS avant d'ouvrir l'image de la page ; en cas de divergence JATS vs PDF, le PDF imprimé prévaut et la divergence est notée. Pas de PMCID : utilisez le PDF.
• PubMed MCP (article non dans le gestionnaire de références) : recherchez par mots-clés, puis récupérez par PMID (un DOI peut renvoyer un full_text vide). Stockez le PMID dans le champ notes: de la fiche article. Utilisez uniquement pour les articles biomédicaux et après que l'utilisateur a confirmé que l'article n'est pas dans sa bibliothèque.
• DOI uniquement : notez-le ; n'inventez pas de métadonnées.
• Article web (HTML/URL en libre accès) : convertissez d'abord en markdown propre avec un outil web-to-markdown (par exemple le skill defuddle), puis traitez la sortie comme résumé et corps. Utilisez l'URL comme source de citation lorsqu'il n'y a pas de DOI.
• Manuel : l'utilisateur colle un résumé ou du texte. Extrayez les métadonnées et signalez ce qui est inconnu.

L'endroit où se trouve le PDF est important : la fiche ne doit jamais citer un dossier de travail (Downloads/, un répertoire temporaire) qui sera nettoyé. Organisez le PDF dans l'emplacement de la bibliothèque utilisé par votre groupe avant d'écrire la fiche, et enregistrez-le dans source_verification. Si l'article n'est pas dans la bibliothèque, ou si la bonne collection n'est pas claire, demandez à l'utilisateur avant de déplacer quoi que ce soit.

3. Déterminer le nom de fichier de la fiche article

Format : PremierAuteur_Année_MotClé.md

• PremierAuteur = nom de famille du premier auteur (ASCII uniquement, pas d'accents, pas d'espaces)
• Année = 4 chiffres
• MotClé = descripteur de 1 à 3 mots (CamelCase ou underscores, pas d'espaces)
• Exemple : Smith_2023_Entraînement_Excentrique.md

Vérification des doublons et de l'identité (à exécuter avant toute écriture ; elle protège contre la perte silencieuse de données) :

1. Confirmez l'existence avec une recherche de contenu pour le nom de base, ou test -f "<wiki_root>/papers/{filename}.md". NE faites PAS confiance à un seul glob renvoyant "aucun fichier trouvé" : les outils de glob de fichiers ont déjà renvoyé des faux négatifs pour des notes qui existaient, et une écriture aveugle Write écraserait une note déjà propagée. Si Write renvoie une erreur "Le fichier n'a pas encore été lu", c'est la preuve que la note existe : lisez-la et mettez-la à jour sur place, ne la réécrivez jamais à partir de zéro.
2. Si la note existante est status: stub, ne supposez pas qu'il s'agit du même article. Les stubs créés à partir du contexte de citation d'un autre article portent des métadonnées provisoires et sont parfois un article différent (mauvaise année, article vs chapitre de livre, deux articles frères confondus). Résolvez d'abord la source réelle et comparez les auteurs, l'année et la revue à la fois avec le stub et la liste de références de la note citante. S'il s'agit d'un article différent, ingérez-le comme une NOUVELLE note et conservez ou améliorez le stub.
3. Si confirmé comme le même article, mettez à jour sur place ; ne créez jamais de doublon. Le nom de fichier peut légitimement changer pour un mot-clé plus descriptif une fois que vous avez le texte intégral. Si c'est le cas, reassociez chaque [[AncienNom]] et supprimez le stub orphelin, puis réexécutez wiki-lint pour confirmer qu'il ne reste aucun lien brisé.
4. Contrôle d'identité par citekey. Deux fiches pour le même article peuvent porter des noms de fichier différents, donc une sonde propre du nom de base ne prouve rien sur l'identité. Une fois que le gestionnaire de références a résolu l'élément, recherchez dans papers/ le citekey exact que vous êtes sur le point d'écrire (grep -l '^citekey: "\?{citekey}"\?$' papers/*.md). Un résultat sur un nom de fichier différent signifie que l'article est déjà ingéré : mettez cette note à jour à la place. Correspondance exacte de chaîne, donc pas de faux positifs.

4. Créer ou mettre à jour la fiche article

Écrivez <wiki_root>/papers/{filename}.md à partir de templates/paper.md. Remplissez chaque champ frontmatter à partir des métadonnées résolues. Définissez last_verified à la date d'aujourd'hui (l'ingestion est un événement de vérification). Attribuez research_lines à partir des slugs de taxonomie dans WIKI_SCHEMA.md.

5. Extraire et évaluer

Un seul passage sur le résumé, les résultats et la discussion, en faisant tout cela à la fois :

• Identifiez 3 à 8 concepts du domaine (construits empiriques, variables) et 1 à 4 méthodes principales. Heuristiques dans references/INGEST-WORKFLOW.md.
• Classez evidence_level : le plan d'étude, à partir du vocabulaire contrôlé dans WIKI_SCHEMA.md (SR-MA, RCT, cohort, ...). C'est l'axe conception que la couche de synthèse vivante pondère. L'axe qualité de mesure reste en ligne dans chaque résultat lorsque pertinent ((IRM), (estimation anthropométrique)), jamais dans le frontmatter.
• Routage des lignes de recherche : faites correspondre l'article aux lignes de recherche dans WIKI_SCHEMA.md. Si le contenu pertinent n'a pas de ligne correspondante, ajoutez-en une au schéma avant de propager (ajoutez une paire slug + label ; ne renommez ni ne supprimez jamais les lignes existantes). Si limite, utilisez la ligne la plus proche et signalez-le dans le rapport.
• Routage concept vs méthode : les résultats empiriques vont dans concepts/ ; les outils statistiques, les plans d'étude et les protocoles de mesure vont dans methods/. Décidez ici.
• Raccourci purement méthodologique : si l'article ne fait aucune affirmation empirique, sautez l'étape 6 et allez à l'étape 7.

5b. Tableau des preuves, avant toute propagation

Pour chaque résultat qui atteindra une note dans concepts/ ou methods/ (y compris une affirmation sous "Articles Utilisant Cette Méthode"), écrivez une ligne dans un fichier temporaire (jamais dans le wiki) :

| Note cible | Résultat, tel qu'il sera écrit | Citation textuelle de la source | Page (PDF / imprimé) | Section, tableau ou figure |

• La source est le PDF (ou le JATS pour les cellules de tableau). Résumé uniquement ou pas de PDF : marquez le résultat abstract only dans son texte et dites-le dans le rapport.
• Chaque spécificité a besoin de sa citation : chaque figure, population, dispositif, mécanisme, entité nommée et verbe de force. Divisez le résultat, ou utilisez plusieurs citations, jusqu'à ce que tout soit couvert.
• Lisez tout le paragraphe ou la ligne de tableau autour du résultat, pas seulement le nombre correspondant.
• Tableaux, figures, signes, IC et ± : affichez la page et regardez-la. L'extraction de texte est une hypothèse, l'image est la preuve. Certains PDF perdent le signe moins dans la couche texte (-5,2% s'extrait comme 25,2%), produisant un nombre faux plausible.
• L'absence nécessite une recherche positive, à la fois dans le texte mis en page et non mis en page et avec des variantes orthographiques, avant que quoi que ce soit ne soit écrit comme "l'article ne... pas".

5c. Vérifiez le tableau avant d'écrire

Relisez chaque ligne par rapport à sa citation avant que toute note ne soit touchée. Si un sous-agent a extrait l'article, relisez chaque ligne dans le PDF, pas seulement les lignes avec une figure ou un signe. Classes de défauts à juger : déduction au-delà de la source, erreur d'attribution, mauvais nombre, atténuateur perdu, superlatif non soutenu, mauvaise entité, détail inventé, omission.

• Une ligne dont la citation ne la soutient pas est reformulée à la baisse pour correspondre à ce que dit la citation, ou supprimée. La note source n'est pas une preuve : elle vient de la même extraction.
• Gardez l'atténuateur de la source (« peut », « il semble », « pourrait être dû à ») et sa population.
• La propre lecture du wiki est étiquetée comme celle du wiki ; ne l'écrivez jamais comme l'acte ou la conclusion de la source.

Seules les lignes qui survivent vont aux étapes 6 et 7.

6. Propager aux fiches de concepts

Pour chaque concept de l'étape 5 :

1. Vérifiez si concepts/{Nom_Concept}.md existe.
2. Existe : ajoutez le résultat avec un lien [[fiche_article]] sous "Résultats Clés". Mettez à jour related_concepts si de nouveaux liens apparaissent.
3. N'existe pas : appliquez d'abord les règles de création dans references/CONCEPT-PROPAGATION.md.

7. Propager aux fiches de méthodes

Pour chaque méthode de l'étape 5 :

1. Vérifiez si methods/{Nom_Méthode}.md existe.
2. Existe : ajoutez l'article sous "Articles Utilisant Cette Méthode".
3. N'existe pas : créez à partir de templates/method.md.

8. Mettre à jour le frontmatter de la fiche article

Remplissez concepts_touched avec les fiches de concepts et de méthodes créées ou mises à jour.

Vérifier après écriture : chaque nom dans concepts_touched DOIT correspondre à une note existante dans concepts/ ou methods/. Après avoir écrit, revérifiez chaque nom de base. Si l'un d'eux ne correspond pas, soit créez le stub manquant maintenant, soit supprimez le nom. Les références pendantes deviennent une dérive de lint silencieuse.

8b. Sceller la note source

Enregistrez la vérification dans source_verification de la fiche article (une ligne : clé du gestionnaire de références, date, ce qui a été vérifié par rapport à quoi). Scellez ensuite chaque paire (note, œuvre) qui a reçu un résultat et dont les lignes ont passé 5c : écrivez une petite spécification JSON et exécutez python <kit>/tools/seal.py spec.json --dry-run, puis sans --dry-run (format et règles dans docs/SEALS.md). Une œuvre vérifiée uniquement par rapport à son résumé n'obtient pas de sceau. Prenez les dates de l'horloge système (date +%F), ne les estimez jamais.

9. Clôture

Trois modifications, puis le rapport. Utilisez field_titlecase_map de wiki.config.json pour trouver la bonne sous-section pour chaque nouveau concept ou méthode ; n'ajoutez jamais à un bloc fourre-tout daté à la fin d'une section.

• index.md : si l'index intègre des vues Obsidian Bases (index_mode: bases dans la config), ne maintenez PAS de listes par note ; augmentez uniquement les compteurs de la section ## Quick Stats et la ligne ## Coverage by Field concernée, puis relisez les tableaux (un wiki frais n'a aucune de ces sections : sautez cela, rien ne dérive jusqu'à ce que vous les ajoutiez). En mode manual, ajoutez la note à la bonne case alphabétique. Ne touchez jamais à un index legacy gelé.
• Routage sous-MOC (voir WIKI_SCHEMA.md, Architecture des Sous-MOC) : résolvez le field + subfield de la note, calculez fields/{field-slug}/MOC_{Title_Case_Underscore(subfield)}.md (kebab-case vers Title_Case, déterministe, pas de carte nécessaire). Si elle n'existe pas, créez-la à partir de templates/submoc.md et ajoutez une ligne à l'index des Sous-MOC du MOC du domaine. Ajoutez la note dans la bonne section du sous-MOC (Notes de Concepts, Notes de Méthodes, Articles, Livres).

… [tronqué pour la traduction]