Citation extraction

Zitat-Extraktion

Gemeinsames Preamble laden: Lies skills/_common/preamble.md und befolge alle dort definierten Blöcke (Vorbedingungen, Keine Fabrikation, Aktivierung, Abgrenzung), bevor du mit diesem Skill-spezifischen Inhalt fortfährst.

Übersicht

Extrahiert und formatiert Zitate aus PDFs und Volltexten. Liefert Literaturverzeichnisse im Zitationsstil aus ./academic_context.md (APA7, IEEE, Harvard etc.). Standard: lokale Extraktion + serverseitige local-verbatim-Verifikation, kein API-Key nötig.

Abgrenzung

Extrahiert und formatiert wörtliche Zitate aus PDFs für einzelne Belege. Für Kapitel-Prosa, die Belege in Argumentation einbaut → chapter-writer (ruft citation-extraction bei Bedarf auf).

BibTeX-Abgrenzung: „BibTeX aus Vault" / „komplette Bibliographie als .bib" → latex-export --bib, nicht hierher (Details → references/output-formats.md).

Variant-Selector

Feld Zitationsstil aus ./academic_context.md; leer → apa.md, unbekannt → Rueckfrage. Datei: ${CLAUDE_PLUGIN_ROOT}/skills/citation-extraction/references/<variant>.md.

Stil	Datei	Stil	Datei
APA7 (Default)	apa.md	MLA	mla.md
Harvard	harvard.md	Vancouver	vancouver.md
Chicago	chicago.md	Springer Author-Date	springer-author-date.md
DIN 1505-2	din1505.md

Typ-Erweiterung (Vorrang vor Artikel-Regeln): type: chapter → book-chapter-de.md; type: book → din1505.md (Monografie-Sektion); type: article-journal → keine Zusatz-Referenz.

Zitat-Extraktion (lokal, kein API-Key)

vault.add_quote(..., extraction_method="local-verbatim") — der quote-extractor-Agent liest das PDF lokal (Read), der Vault-Server prüft den Wortlaut fail-closed gegen den PDF-Volltext. Seit #632 der einzige Weg; extraction_method="citations-api" bleibt optionaler Alt-Wert für Bestandszitate, wird aber nicht mehr neu erzeugt.

Output: pdf_page aus vault.find_quotes/vault.get_quote → references/output-formats.md.

Kontext-Dateien

• Lesen: ./academic_context.md (Zitationsstil)
• Vault-Queries: vault.find_quotes(paper_id, query), vault.get_quote(quote_id)
• ./literature_state.md: read-only Snapshot, nicht schreiben

Core-Workflow

1. Extraktions-Scope bestimmen

Kläre, was der User braucht:

• Vollextraktion — Alle in der Session heruntergeladenen PDFs verarbeiten
• Kapitelbezogen — Zitate für ein bestimmtes Kapitel extrahieren
• Quellenbezogen — Aus einem oder mehreren bestimmten Papern extrahieren
• Themenbezogen — Zitate zu einem Konzept über alle Quellen hinweg suchen

2. Relevante Paper aus Vault laden

Rufe vault.search(query, k=5) auf für die relevantesten Paper-IDs. Für jeden paper_id:

1. vault.find_quotes(paper_id, query=research_query, k=10) → [{quote_id, verbatim, pdf_page, section, ...}]
2. Details: vault.get_quote(quote_id)

Fehlen Vault-Zitate (leere Liste): quote-extractor-Agent spawnen (Ablauf → Schritt 3). Persistiert wird nur, sofern kein PDF-Mismatch vorliegt — siehe PDF-Mismatch-Gate in Schritt 3.

3. Zitat-Extraktion

Wenn Vault-Zitate für ein Paper vorhanden sind, diese direkt verwenden — kein Agent-Spawn nötig.

Fehlen Vault-Zitate, den Agent quote-extractor spawnen (definiert in ${CLAUDE_PLUGIN_ROOT}/agents/quote-extractor.md). Übergebe:

{
  "paper": { "paper_id": "mueller2023", "title": "Paper Title" },
  "research_query": "derived from chapter title or user query",
  "max_quotes": 3,
  "max_words_per_quote": 25
}

Der Agent liest das PDF lokal (vault.get_paper → pdf_path → Read) und liefert vault_quote_id, possible_pdf_mismatch, extraction_quality. Persistenz via vault.add_quote(..., extraction_method="local-verbatim") nur bei possible_pdf_mismatch: false — sonst erst nach dem Gate, per Re-Invoke mit mismatch_override: true.

Bei kapitelbezogener Extraktion den research_query aus Kapiteltitel und Schlüsselkonzepten der Gliederung ableiten. Die Gliederungs-Struktur aus ./academic_context.md nutzen, um Paper zu Kapiteln zu matchen.

PDF-Mismatch-Gate

Bei possible_pdf_mismatch: true vor jeder weiteren Persistenz AskUserQuestion stellen — kein reines Flaggen für späteres Review:

• "Fortfahren — Zitate trotz Mismatch übernehmen" → Agent-Re-Invoke mit mismatch_override: true (Agent persistiert selbst, kein Skill-Persist)
• "Paper überspringen" → Sessionlokal als "Ausgelassen" markieren, kein Vault-Persist (nicht in excluded_sources schreiben — siehe references/pdf-mismatch-gate.md)
• "PDF-Zuordnung prüfen" → pausieren, kein Persist, User klärt die Zuordnung (z. B. vault.update_pdf_path)

Ohne Freigabe aus diesem Gate wird kein Zitat des Papers persistiert.

4. Qualitätsprüfung

Nach der Extraktion:

• extraction_quality: "failed" → verwerfen
• possible_pdf_mismatch: true → PDF-Mismatch-Gate aus Schritt 3, kein eigenständiges Flaggen mehr an dieser Stelle
• Relevanz fürs Zielkapitel prüfen, Duplikate über Paper hinweg entfernen

Ergebnispräsentation getrennt nach Ausgang:

• Erfolgreich — persistierte Zitate nach Quelle gruppiert: Zitattext, Seitenzahl, Abschnitt, Relevanz-Score, Paper-Titel, Autoren.
• Ausgelassen — im Gate übersprungene oder pausierte Paper; zählen nicht als erfolgreich, eigene Gruppe im Report.

5. Zitat-Formatierung

Formatiere Zitate inline nach dem in ./academic_context.md konfigurierten Stil — keine externe Skript-Pipeline, Claude generiert direkt aus den strukturierten Paper-Daten. Output-Formate → references/output-formats.md.

6. Kapitelzuordnung

Bei kapitelbezogener Extraktion: Zitate nach Relevanz für die Unterabschnitte gruppieren, Platzierung vorschlagen, Lücken in der stützenden Evidenz benennen und dort weitere Suche anbieten.

Gate: Der Vorschlag gilt erst nach AskUserQuestion-Bestätigung als angenommen — vor Export/Weiterverwendung:

• „Übernehmen" — Vorschlag weiterverwenden
• „Ablehnen" — verworfen, kein Vault-Schreibzugriff; zurück zu Schritt 5

Ablehnung ist Default-Pfad, kein Fehler.

7. Literaturstatus

Der Vault ist die Quelle der Wahrheit; ./literature_state.md ist ein read-only Snapshot — nicht beschreiben. Regenerieren:

node scripts/export-literature-state.mjs

Zitatanzahlen und Coverage über vault.stats(). Backend-Zustand (Embedding-Modell, sqlite-vec) via vault.component_status().

Lückenerkennung

Muster (fehlende Zitate, Einzelquellen, fehlende Gegenargumente, veraltete Quellen) und Handlungsempfehlungen → references/gap-detection.md.

Export-Formate

Unterstützte Output-Formate (BibTeX, Markdown, JSON; inline generiert, kein externes Skript). Details und Ziel-Pfade → references/output-formats.md.

Few-Shot-Beispiele

Gut/Schlecht-Beispiele zur Qualitätskalibrierung (APA7-Zitation, Bibliography-Vollständigkeit) → references/citation-examples.md.

Wichtige Regeln

• Nie fabrizieren — nur Text direkt aus PDFs
• Exakter Wortlaut — wörtlich zur Quelle
• Seitenzahlen — wenn verfügbar immer mitführen
• Zitationsstil respektieren — durchgehend den konfigurierten Stil
• Mismatches gaten — possible_pdf_mismatch: true löst vor jeder Persistenz das Gate aus Schritt 3 aus (kein reines Flaggen)
• User bestätigt Zuordnungen — Gate in Schritt 6 (AskUserQuestion)