Dokumentenentwicklungs-Tracker

---

name: document-evolution-tracker

description: "Dokumentenentwicklungs-Tracker. Verwenden Sie dies, wenn der Benutzer eine Familie von Dokumentversionen (mit Zeitstempel oder sequenziell benannte Dateien) hat und sehen möchte, wie sich das Dokument im Laufe der Zeit verändert hat – welche Absätze/Zeilen/Sätze zwischen aufeinanderfolgenden Versionen hinzugefügt, entfernt oder geändert wurden und wie sich eine Reihe von benannten Konzepten (oder automatisch erkannten Überschriften) entwickelt hat (eingeführt/beibehalten/geändert/entfernt). Löst bei "track document changes", "version history", "what changed between drafts", "concept lineage", "document evolution" aus. Gibt eine Markdown + JSON-Zeitleiste aus."

metadata: author: Jiaming Shi version: 1.0.0 license: MIT entry_point: python -m src.cli python_requires: '>=3.9' optional_dependencies: - 'PyYAML>=6.0' platforms: - windows - macos - linux legacy_name: document-evolution-tracker

document-evolution-tracker

Ein eigenständiger Skill, der verfolgt, wie sich ein Dokument über Versionen hinweg entwickelt. Bei einer Versionsfamilie (einem Verzeichnis mit v1.md, v2.md, ... oder Dateien mit Zeitstempeln) berechnet er absatzgenaue Unterschiede zwischen aufeinanderfolgenden Versionen und verfolgt eine Konzeptlinie (eingeführt / beibehalten / geändert / entfernt).

ERZWUNGENER WORKFLOW

Abhängigkeiten booten (bei der ersten Verwendung)

Vor der ersten Ausführung die Laufzeitabhängigkeiten für diesen Skill prüfen:

• Kern: reine Standardbibliothek – keine Installation erforderlich.
• Optional: PyYAML (nur wenn die Konfiguration eine .yaml-Datei ist; JSON-Konfigurationen arbeiten mit der Standardbibliothek).

Wenn PyYAML fehlt und die Konfiguration YAML ist, den Benutzer informieren und fragen, ob pip install pyyaml ausgeführt werden soll. Nur nach Bestätigung installieren. Niemals ohne ausdrückliche Zustimmung in die globale Umgebung installieren.

1. Eine Konfiguration laden (config/examples/family.json als Referenz; YAML-Konfigurationen werden ebenfalls unterstützt, wenn PyYAML installiert ist).
2. Sicherstellen, dass versions_dir mindestens zwei versionierte Dateien enthält.
3. python -m src.cli run --config <pfad> [--concepts "A,B"] ausführen.
4. Die Anzahl der Übergänge melden und den Benutzer auf ./evolution/evolution_<tracking_id>.{md,json} verweisen.

Wann verwenden

• Eine Familie von Dokumentversionen (mit Zeitstempel oder sequenziell benannt) muss über die Zeit verglichen werden.
• Der Benutzer fragt nach "Verfolge Dokumentänderungen", "Versionsgeschichte", "Was hat sich zwischen Entwürfen geändert" oder "Konzeptlinie".
• Ein benanntes Konzept (ein Begriff, eine Überschrift, eine Definition) muss über Entwürfe hinweg verfolgt werden, um zu sehen, wann es eingeführt, geändert oder entfernt wurde.
• Die Entwicklung eines Entwurfs muss als Zeitleiste und nicht als einmaliger durchgehender Diff gemeldet werden.

Verwendungsbeispiele

# Eine Konfiguration validieren und die entdeckten Versionsdateien anzeigen.
python -m src.cli validate --config config/examples/family.json
python -m src.cli versions --config config/examples/family.json

# Den Tracker ausführen; optional die zu verfolgenden Konzepte benennen.
python -m src.cli run --config config/examples/family.json --concepts "entropy,partition function"

Berichte werden nach ./evolution/evolution_<tracking_id>.{md,json} geschrieben; die Markdown-Zeitleiste ist für Leser, das JSON für die programmatische Verwendung.

Fehlerbehandlung

• Konfiguration ungültig (validate beendet mit Fehlercode) – das gemeldete Feld korrigieren und erneut validieren; das Benennungsschema und versions_dir sind die üblichen Übeltäter.
• Weniger als zwei Versionen gefunden – die Ausführung wird abgebrochen; die version_naming-Regel mit den tatsächlichen Dateinamen überprüfen und erneut versuchen.
• Ein Konzept erscheint nie – es wird als in allen Versionen abwesend gemeldet, was ein gültiges Ergebnis ist, kein Fehler.
• Unerwarteter Exit-Code – die Meldung wörtlich melden; nicht auf manuelles Diffing der Dateien zurückfallen.

Diff-Granularität

Granularität	Aufteilungsregel
line	Nicht-leere Zeilen
paragraph (Standard)	Durch Leerzeilen getrennte Blöcke
sentence	Durch Satzzeichen getrennte Sätze

Einschränkungen

• Das Diffing ist strukturell (Blockausrichtung über difflib), nicht semantisch. Ein Konzept ist nur dann "vorhanden", wenn sein exakter Begriff (Groß-/Kleinschreibung nicht beachtet) im Text der Version vorkommt.
• Benutzerdefinierte Benennungsschemata über sequential / timestamp hinaus werden nicht unterstützt.