Moonweave-Research/ref-verify

ref-verify — Referenz-Halluzinations-Schutz

Der spezifische Fehler, den dieses Skill verhindert: LLMs beschreiben den Inhalt eines Papiers aus abgerufenen Trainingsdaten, anstatt aus dem, was das Abstract tatsächlich sagt. Einem Paper werden Ergebnisse zugeschrieben, die es nicht enthält, oder es wird für Behauptungen zitiert, die im Text nirgends vorkommen. Die Lösung ist eine Regel, die konsequent angewendet wird:

Jede inhaltliche Aussage über ein Paper muss aus einer live abgerufenen Quelle stammen – Abstract für übergeordnete/überschriftähnliche Behauptungen, Volltext für Mechanismus-/Implementierungs-/Verfahrensbehauptungen – wörtlich zitiert oder direkt paraphrasiert. Wenn Sie die erforderliche Quelle nicht abrufen können, sagen Sie dies explizit – füllen Sie die Lücke niemals mit einer erinnerten Beschreibung, und lassen Sie niemals einen thematischen Abstract-Treffer als Ersatz für eine Mechanismus-bezogene Behauptung gelten.

---

Modusentscheidung

Wählen Sie den Modus, bevor Sie mit der Arbeit beginnen. Die Wahl steuert Kosten und Tiefe.

Benutzer gibt DOI(s) für Plausibilitätsprüfung an?
  └─ ≤10 Referenzen → Quick Screen für alle
  └─ >10 Referenzen → Quick Screen für alle; Full Audit nur für MISMATCH/DEAD Ergebnisse

Benutzer sagt „Finde Paper zu X“ oder „Zitiere Paper, die Behauptung Y stützen“?
  └─ Full Audit (Suche von Grund auf erfordert Inhaltsverifikation)

Benutzer sagt „Überprüfe meine Referenzliste“ oder führt Vorab-Einreichungs-Audit durch?
  └─ ≤5 Referenzen  → Full Audit für alle
  └─ >5 Referenzen  → Quick Screen für alle zuerst; Full Audit für MISMATCH/DEAD + jede Referenz,
                 die für eine bestimmte sachliche Behauptung zitiert wird

Benutzer schreibt und fügt ein einzelnes Zitat aus dem Gedächtnis hinzu?
  └─ Quick Screen Minimum; Full Audit, wenn für eine bestimmte Behauptung zitiert wird

Der teure Teil ist Full Audit (5-stufiger, quellentiefe Beweisabruf). Quick Screen kostet ~5s pro Paper. Eskalieren Sie nur zu Full Audit, wenn die Aufgabe tatsächlich eine Inhaltsverifikation erfordert.

---

Ausführbare Engine

Verwenden Sie dies als Skill-Level-Workflow. Erstellen oder benötigen Sie kein MCP für diesen Pfad. Die CLI ist eine Ausführungs-Engine, die das Skill vom Terminal aus aufrufen kann; das manuelle Protokoll bleibt der Fallback und die Quelle der Wahrheit für Ebenen, die die CLI noch nicht abdeckt.

CLI-Verfügbarkeitsprüfung

Vor einer DOI-basierten Prüfung prüfen Sie, ob die ausführbare Engine verfügbar ist:

ref-verify --help

npx skills add installiert das Python-CLI nicht per pip. Wenn das Konsolenskript nicht verfügbar ist, behandeln Sie dies nicht als Verifikationsergebnis.

Wenn das Konsolenskript nicht verfügbar ist, aber der Repository-Quellcode vorhanden ist, verwenden Sie:

PYTHONPATH=src python3 -m ref_verify.cli --help

Wenn beide Befehle fehlschlagen, folgen Sie dem untenstehenden manuellen Fallback-Protokoll. Tun Sie nicht so, als ob die CLI gelaufen wäre, und erfinden Sie kein Ergebnis aus dem Gedächtnis.

CLI-erster Workflow

Verwenden Sie die CLI zuerst, wenn der Benutzer eine DOI angibt oder fragt, ob ein DOI-gebundenes Abstract eine bestimmte sachliche Behauptung stützt. Der aktuelle CLI-Umfang ist CrossRef Metadatenverifikation plus DOI-gebundene Abstract-Anspruchsprüfungen. Anspruchsprüfungen verwenden CrossRef zuerst, dann DOI-gebundene OpenAlex, Semantic Scholar und PubMed Fallback, wenn CrossRef kein Abstract hat.

CrossRef Metadaten-Screen:

ref-verify verify-doi <doi> \
  --title "<bereitgestellter Titel>" \
  --first-author <bereitgestellter-erstautor-nachname> \
  --year <bereitgestelltes-jahr> \
  --json

Source-Checkout-Fallback:

PYTHONPATH=src python3 -m ref_verify.cli verify-doi <doi> \
  --title "<bereitgestellter Titel>" \
  --first-author <bereitgestellter-erstautor-nachname> \
  --year <bereitgestelltes-jahr> \
  --json

verify-doi beendet sich mit Exit-Code 0 nur bei PASS; WARN und REJECT geben einen Fehlercode zurück. Die Angabe nur einer DOI prüft, ob CrossRef auflöst, reicht aber nicht aus, um die Metadatenverifikation zu bestehen.

Leiten Sie das Ergebnis:

• PASS: Melden Sie die Metadaten-Übereinstimmung, fahren Sie dann mit Layer 4 DOI-Landingpage-Auflösung und Layer 5 Retraktionsprüfungen fort, wenn der ausgewählte Modus diese erfordert.
• WARN: Melden Sie die fehlenden oder schwachen Metadaten, fahren Sie dann mit dem manuellen Fallback für die fehlenden Layer fort, anstatt die Referenz stillschweigend zu akzeptieren.
• REJECT: Beenden Sie die Verwendung dieses Zitats als verifiziert; melden Sie die Abweichung und bitten Sie um eine korrigierte DOI oder ein korrigiertes Zitat, es sei denn, der Benutzer wünscht explizit Alternativen.

Einzelne Anspruchsprüfung gegen ein DOI-Abstract:

ref-verify check-claim <doi> --claim "<spezifische sachliche Behauptung>" --json

Source-Checkout-Fallback:

PYTHONPATH=src python3 -m ref_verify.cli check-claim <doi> --claim "<spezifische sachliche Behauptung>" --json

Standardmäßig verwendet check-claim zuerst CrossRef. Wenn CrossRef kein Abstract hat, versucht es DOI-gebundene OpenAlex, Semantic Scholar und PubMed Fallback-Quellen. Verwenden Sie --source crossref, --source openalex, --source semantic-scholar oder --source pubmed für quellspezifische Fehlersuche. Explizite Nicht-CrossRef-Quellenauswahl umgeht CrossRef, so dass ein OpenAlex-, Semantic Scholar- oder PubMed-Fehler isoliert werden kann.

Leiten Sie das Ergebnis:

• ACCEPT: Zitieren Sie die CLI-Beweise und fahren Sie mit allen erforderlichen manuellen DOI-Auflösungen, Zweitquellen-Existenz und Retraktions-Layern fort.
• WARN oder PARTIAL: Berichten Sie, welche die ausgewählte Abstract-Quelle unterstützte und welche nicht, fahren Sie dann mit dem manuellen Fallback fort, wenn weitere Layer erforderlich sind.
• UNVERIFIABLE: Von den versuchten CLI-Quellen war kein vertrauenswürdiger DOI-gebundener Abstract-Beweis verfügbar. Fahren Sie stattdessen mit der untenstehenden manuellen Fallback-Kette fort, anstatt die Behauptung als abgelehnt oder unterstützt zu behandeln.

CLI ACCEPT ist nur Abstract-Level-Beweis. Wenn die Behauptung einen Mechanismus, eine Implementierung oder ein Verfahren beschreibt, stufen Sie dieses Ergebnis nicht auf das Full Audit-Urteil hoch; klassifizieren Sie die Behauptung in Layer 3 und beschaffen Sie zuerst die erforderlichen Volltext-Beweise.

Für JSON-Ausgabe verwenden Sie abstract_source, source_attempts und error_code, um den nächsten Schritt zu bestimmen:

• CLAIM_SUPPORTED: Explizite Abstract-Unterstützung gefunden.
• CLAIM_NOT_EXPLICIT: Ein Abstract war verfügbar, aber die Behauptung wurde nicht explizit unterstützt.
• CLAIM_AMBIGUOUS: Numerische Beweise oder Kontext existieren, aber die Bindung ist mehrdeutig.
• NO_ABSTRACT: Die versuchten DOI-gebundenen Quellen haben keinen Abstract-Text bereitgestellt.
• DOI_NOT_FOUND: Die ausgewählte Quelle hat keinen DOI-gebundenen Datensatz gefunden.
• DOI_MISMATCH: Der primäre oder explizit ausgewählte DOI-gebundene Datensatz stimmte nicht mit der angeforderten DOI überein.
• SOURCE_API_ERROR, SOURCE_TIMEOUT, SOURCE_RATE_LIMITED, SOURCE_UNSUPPORTED: Quellensuche fehlgeschlagen, abgelaufen, ratenbegrenzt oder nicht verwendbar.

Die CLI ersetzt nicht Layer 4 DOI-Landingpage-Auflösung, Zwei-Quellen-Existenzprüfungen oder Retraktionsprüfungen. Fahren Sie für diese Layer mit dem manuellen Protokoll fort, wenn der ausgewählte Modus sie erfordert.

---

Quick Screen — Metadaten- + DOI-Plausibilitätsprüfung

Verwenden Sie, wenn der Benutzer eine DOI oder ein vollständiges Zitat angibt und eine Plausibilitätsprüfung wünscht.

1. CrossRef aufrufen: https://api.crossref.org/works/{DOI}
2. Rückgegebenen Titel + Nachnamen des Erstautors mit den Angaben des Benutzers vergleichen
3. https://doi.org/{DOI} abrufen — bestätigen, dass es auflöst und auf dem richtigen Paper landet
4. Eine Zeile pro Referenz melden:

Smith et al. (2021) 10.1234/example — PASS (Titel/Autor stimmen überein, DOI löst auf)
Jones (2019) 10.5678/other — MISMATCH (CrossRef: Jones & Lee 2019, nicht Jones allein)
Kim (2023) 10.9999/fake — DEAD DOI

Zu Full Audit eskalieren, wenn: DOI auf ein anderes Paper auflöst, ein Feld nicht übereinstimmt oder der Benutzer für eine bestimmte sachliche Behauptung zitiert.

---

Full Audit — für Literaturrecherche oder Vorab-Einreichungsprüfung

Verwenden Sie beim: Suchen von Papern zur Unterstützung einer Behauptung oder Durchführen einer abschließenden Zitierprüfung.

Führen Sie alle fünf Layer pro Paper aus. Die Layer sind danach geordnet, was sie abfangen — überspringen Sie keine.

Layer 1 — Existenz

Durchsuchen Sie zwei Quellen unabhängig:

• CrossRef: https://api.crossref.org/works?query.bibliographic={titel+autor}&rows=5
• Semantic Scholar: https://api.semanticscholar.org/graph/v1/paper/search?query={titel+autor}&fields=title,authors,year,externalIds,abstract&limit=5
• arXiv für Preprints: https://export.arxiv.org/api/query?search_query=ti:{titel}&max_results=3

Ein Paper wird nur bestätigt, wenn die Titel im Wesentlichen übereinstimmen und der Nachname des Erstautors in zwei Quellen übereinstimmt.

• Treffer in zwei Quellen → CONFIRMED
• Eine Quelle → SINGLE-SOURCE ⚠ — mit Vorsicht fortfahren, in der Ausgabe vermerken
• Null → NOT FOUND ✗ — anhalten; klar melden; keinen Ersatz erfinden

Layer 2 — Metadaten

Aus bestätigten Quellen extrahieren und vergleichen: Titel, alle Autoren (Nachnamen), Jahr, vollständiger Zeitschriftenname, DOI, Band/Seiten (mit [NOT IN SOURCE] markieren, wenn nicht vorhanden). Wenn ein Feld zwischen den Quellen abweicht, beide anzeigen — nicht stillschweigend eines auswählen.

Layer 3 — Inhaltliche Nachvollziehbarkeit ← wichtigster Layer

Hier liegt der Kernwert des Skills. Das Ziel ist nicht nur „existiert dieses Paper“, sondern „enthält dieses Paper tatsächlich die Behauptung, die ihm zugeschrieben wird?“

Schritt 0 — Klassifizieren Sie die Behauptung.

Bevor Sie etwas abrufen, klassifizieren Sie, um welche Art von Behauptung es sich handelt:

• Übergeordnete/überschriftähnliche Behauptung — ein Ergebnis der Art, die Abstracts konventionell nennen (Gesamtergebnis, übergeordnete Zahl, allgemeine Schlussfolgerung). Abstract-alleinige Beweise sind eine legitime Quelle der Wahrheit für diese Klasse.
• Mechanismus-/Implementierungs-/Verfahrensbehauptung — beschreibt wie etwas funktioniert oder gemacht wurde: ein spezifischer Mechanismus, Algorithmus, Architektur, Parameter, experimenteller Schritt, Kontrollbedingung oder ein numerischer Wert, der an eine Tabelle/Abbildung/Methodenabschnitt gebunden ist und nicht an das zusammenfassende Ergebnis. Abstracts enthalten diesen Inhalt routinemäßig nicht, selbst wenn das Paper ihn unterstützt. Signalwörter: „Mechanismus“, „wie“, „Architektur“, „Algorithmus“, „Implementierung“, „Verfahren“, „Protokoll“, „Parameter“, „Kontrollgruppe“, „Ablation“, „Tabelle“, „Abbildung“ oder jede Behauptung, die spezifischer ist als das, was eine einabsätzige Zusammenfassung aussagen würde.

Wenn die Behauptung Mechanismus/Implementierungs-Klasse ist, ist eine reine Abstract-Prüfung nicht ausreichend, selbst wenn das Abstract thematisch passt. Rufen Sie das Abstract als Beweis für Existenz/Themenübereinstimmung ab, aber entscheiden Sie das Urteil nicht allein aus dem Abstract — fahren Sie mit Layer 3b unten fort.

Rufen Sie das Abstract in dieser Prioritätsreihenfolge ab:

1. CrossRef rohes JSON: https://api.crossref.org/works/{DOI} — prüfen Sie das Feld abstract
2. OpenAlex: https://api.openalex.org/works/doi:{DOI}?mailto={kontakt_email} — rekonstruieren Sie abstract_inverted_index
3. Semantic Scholar: hängen Sie &fields=abstract an Ihre S2 DOI-Suche an
4. Open-Access-Fallback: https://api.unpaywall.org/v2/{DOI}?email={kontakt_email} — prüfen Sie is_oa und oa_locations
5. arXiv Fallback für Preprints: https://export.arxiv.org/api/query?id_list={arxiv_id}
6. PubMed Central für Life/Bio-Paper: https://www.ncbi.nlm.nih.gov/pmc/articles/{PMCID}/

Ersetzen Sie für APIs, die eine Kontakt-E-Mail erfordern, {kontakt_email} durch eine echte, vom Benutzer autorisierte Adresse aus der Konfiguration. Senden Sie keine Platzhalteradresse.

Nach dem Abruf prüfen Sie: Enthält das Abstract die spezifische Behauptung, die zitiert wird?

• Abstract enthält die Behauptung explizit (wörtlich zitieren) → CONTENT: SUPPORTED
• Abstract handelt vom Thema, enthält aber nicht die spezifische Behauptung → CONTENT: PARTIAL — zitieren, was es tatsächlich sagt
• Abstract widerspricht der Behauptung → CONTENT: CONTRADICTED — dieses Zitat nicht verwenden
• Abstract nach Versuch aller Quellen nicht zugänglich → CONTENT: UNVERIFIABLE — Benutzer muss Volltext prüfen
• Behauptung ist Mechanismus/Implementierungs-Klasse und Volltext konnte nach Versuch aller Layer 3b Quellen nicht bezogen werden → CONTENT: ABSTRACT-ONLY — Volltext nicht verfügbar, Verifikation unzureichend. Dieses Label darf niemals zu SUPPORTED/ACCEPT hochgestuft werden.

Die Regel, die nicht gelockert werden darf: Wenn Sie beschreiben, was ein Paper „zeigt“ oder „demonstriert“ oder „berichtet“, müssen Sie abgerufenen Quelltext in der erforderlichen Tiefe zitieren oder direkt paraphrasieren. Das Zusammenfassen aus dem Gedächtnis ist nicht erlaubt, selbst wenn Sie sich sicher fühlen.

Layer 3b — Volltext-Bestätigung (nur für Mechanismus/Implementierungs-Klasse)

Erforderlich, wann immer Schritt 0 die Behauptung als Mechanismus/Implementierungs-Klasse klassifiziert hat, oder wann immer das Abstract-Urteil PARTIAL für eine Behauptung ist, die spezifischer ist als die Zusammenfassungsstufe des Abstracts. Nur für übergeordnete Behauptungen überspringen, die CONTENT: SUPPORTED direkt aus dem Abstract erhalten haben.

Rufen Sie den Paper-Volltext in dieser Prioritätsreihenfolge ab, stoppen Sie beim ersten Erfolg:

1. Lokales Zotero-PDF — Wenn eine Zotero-Bibliothek konfiguriert ist, fragen Sie ihre Datenbank nach dieser DOI ab, lösen Sie den Anhangsschlüssel auf und lesen Sie das verknüpfte PDF. Ein häufiger Standard ist ~/Zotero/zotero.sqlite mit Anhängen unter ~/Zotero/storage/{key}/; finden Sie den tatsächlichen Pfad heraus, anstatt ihn anzunehmen.
2. research-wiki Vault — Wenn das research-wiki Skill verfügbar ist, durchsuchen Sie sein konfiguriertes Vault nach einer bereits aufgenommenen Volltextkopie. Nehmen Sie keinen maschinenspezifischen Vault-Pfad an.
3. Open-Access-Link — Lösen Sie den eigentlichen Volltext auf und rufen Sie ihn ab (nicht nur eine Verfügbarkeitsmarkierung):
   • Unpaywall: https://api.unpaywall.org/v2/{DOI}?email={kontakt_email} → rufen Sie best_oa_location.url_for_pdf (oder beliebige oa_locations[].url_for_pdf) ab.
   • arXiv: https://export.arxiv.org/api/query?id_list={arxiv_id} → rufen Sie das vollständige Paper ab, nicht nur das <summary>. Feld.
4. Fehler — Wenn keine der oben genannten Methoden einen lesbaren Volltext liefert, behandeln Sie das Abstract nicht als ausreichend. Wenden Sie das oben definierte Label CONTENT: ABSTRACT-ONLY an.

Wenn der Volltext erhalten wird, zitieren Sie die Passage, die die Behauptung stützt, teilweise stützt oder ihr widerspricht. Für eine Mechanismus/Implementierungs-Behauptung erfordert CONTENT: SUPPORTED ein Volltext-Zitat — eine Abstract-Level-Themenübereinstimmung kann es nicht erfüllen.

Layer 4 — DOI-Auflösung

Rufen Sie https://doi.org/{DOI} ab. Bestätigen Sie, dass die Landingpage dem erwarteten Paper entspricht. Ein 403 (Bot-Blockierung) von einem URL-Slug, der den Titel und den Band enthält, ist kein toter Link — notieren Sie ihn als paywalled. Eine Weiterleitung zu einer nicht verwandten Seite ist ein kritischer Fehler.

Layer 5 — Retraktion

Suchen Sie nach "{Nachname des Erstautors}" "{Zeitschriftenname}" retraction und prüfen Sie die DOI-Landingpage auf Retraktionsbanner. Ein zurückgezogenes Paper darf nicht als Primärquelle verwendet werden.

---

Ausgabeformat

Quick Screen: eine Zeile pro Referenz (siehe oben).

Full Audit: eine Karte pro Paper, dann eine Zusammenfassungstabelle.

REFERENCE-AUDIT
────────────────────────────────────────────────
Paper:   [Titel aus Live-Quelle — nicht aus dem Gedächtnis]
DOI:     [DOI] — [✓ Löst auf | ✗ Tot | ✗ Falsches Paper | ⚠ Paywalled-403]
Autoren: [Vollständige Liste der Autorennamen aus Live-Quellen — nicht aus dem Gedächtnis]