Arzaroth/skills

docs-update

Dokumentation fault still vor sich hin: Nichts schlägt fehl, der Text hört nur auf, wahr zu sein. Dieses Skill findet die Dokumente, die die letzten Änderungen hätten berühren sollen, und bringt sie auf den neuesten Stand.

Die folgenden Befehle schreiben ~/.claude/skills/docs-update/scripts/ vollständig aus. Führe sie genau so aus, wie sie geschrieben sind – behalte die führende ~ bei und ersetze sie nicht. Eine Berechtigungsregel prüft auf den exakten Befehlsstring, also /home/<du>/.claude/... (die Tilde expandiert), python3 ~/..., ein relativer Pfad oder ein vorangestelltes cd sind jeweils unterschiedliche Strings und führen erneut zu einer Rückfrage. Ein Tildenpfad ist nicht „der absolute Pfad, informell geschrieben“ – für eine Berechtigungsregel ist er der Pfad.

Dokumentation wird mit der Änderung ausgeliefert, nicht danach. Wenn du auf einem Feature-Branch arbeitest, committe die Dokumentation auf diesen Branch, damit der Merge sie mitnimmt. Ein nachträglicher PR für die Dokumentation ist ein PR für die Dokumentation, den niemand schreibt.

1. Wähle den Umfang

In der Reihenfolge der Priorität:

Der Benutzer hat es gesagt. „vollständiger Durchlauf“, „seit v2.1“, „nur dieser Branch“ – verwende es. Ein vollständiger Durchlauf ist --full und liest alles; er ist die richtige Wahl nach einer längeren Pause oder bei der erstmaligen Verwendung dieses Skills in einem Repository.

Ein Dokument vermerkt seinen eigenen letzten Aktualisierungszeitpunkt:

~/.claude/skills/docs-update/scripts/docscheck.py markers

Wenn ein Dokument Zuletzt aktualisiert: <Datum|SHA> enthält, begrenze dieses Dokument von dort aus (--since). Dokumente, die unterschiedliche Angaben machen, erhalten ihre eigenen Umfänge; es gibt keine einheitliche Antwort.

Andernfalls leite es aus Git ab:

~/.claude/skills/docs-update/scripts/docscheck.py scope

Es bevorzugt den zuletzt gemergten Branch (die Arbeit eines Branches ist die Einheit, die die Leute meinen), mit Rückfall auf den letzten Commit. Überschreibe mit --since <Ref>.

In dieser Sitzung geleistete Arbeit ist der Fall, den das Skript nicht sehen kann. Wenn diese Sitzung die Änderungen vorgenommen hat, kennst du die Dateien bereits; übergib den Vor-Sitzungs-Ref als --since oder arbeite mit deiner eigenen Bearbeitungsliste.

scope trennt kind=code von kind=doc-already-touched. Die zweite Liste ist wichtig: Diese Dokumente wurden zusammen mit der Änderung aktualisiert, also überprüfe sie auf Korrektheit, nicht auf Fehlen.

2. Finde die Dokumente, die die Änderung tatsächlich betrifft

~/.claude/skills/docs-update/scripts/docscheck.py impacted

Für jede geänderte Code-Datei meldet dies die Dokumente, die diesen genauen Pfad nennen. Ein Dokument, das eine von dir geänderte Datei zitiert, ist das Dokument, das am wahrscheinlichsten etwas beschreibt, das nicht mehr wahr ist, und es ist ein weitaus besserer Ausgangspunkt, als jedes Dokument erneut zu lesen.

Es gleicht nur vollständige Pfade ab, absichtlich. Auch übergeordnete Verzeichnisse zu berücksichtigen, klingt großzügiger und ist nutzlos: In einem Monorepo erscheint apps/web-nuxt/ in 55 von 62 Dokumenten, also betrifft alles alles.

result=none ist normal und bedeutet nicht „nichts zu tun“ – es bedeutet, dass kein Dokument diese Pfade nennt, also beurteile stattdessen nach Thema. Das ist Schritt 3.

3. Beurteile nach Thema, unter Verwendung der eigenen Dokumenttaxonomie des Repos

impacted findet Pfadzitate. Es kann kein Dokument finden, das ein von dir geändertes Verhalten beschreibt, ohne eine Datei zu nennen. Also lies die Änderung und frage, was sie bedeutet.

Lerne zuerst, wie dieses Repo Dokumente organisiert – ein brain/, ein docs/, eine CONTEXT.md, ein ADR-Verzeichnis – und folge dieser Struktur, anstatt eine zu erfinden. Wenn ein Projekt-Skill Dokumente abdeckt (.claude/skills/*), hat es Vorrang vor diesem hier.

Die übliche Zuordnung:

Die Änderung	Das Dokument
neues, benutzersichtbares Feature	Feature-Dokument + sein Index/Katalog-Eintrag; README-Feature-Liste
geändertes bestehendes Verhalten	das Dokument dieses Features
Schema, Authentifizierung, Build, Speicher, Echtzeit, Anbieter	das Architektur-Dokument dafür
eine nicht offensichtliche Entscheidung oder eine, die im Review aufgekommen ist	das Entscheidungs-/ADR-Protokoll, mit seinem Warum
neuer Begriff	das Glossar
neue oder geänderte Umgebungsvariable, Befehl, Skript	README und alle Setup-/Ops-Dokumente
neue Abhängigkeit	alle Stack-/Tech-List-Dokumente (diese werden manuell gepflegt und immer vergessen – diff das Manifest)
benutzersichtbare Änderung	CHANGELOG [Unveröffentlicht]

Zwei Fallen:

• Abgeleitete Fakten, eingebettet in Prosa. Ein Dokument, das sagt „aktuelle Version ist 2.16.2“ oder den Tech-Stack auflistet, ist eine Kopie von etwas anderem, das sich geändert hat. Diff die Quelle der Wahrheit (das Manifest, die Versionsdatei), anstatt der Prosa zu vertrauen.
• Dokumente, die historisch oder zukunftsorientiert sein sollen. CHANGELOG-Einträge, TODO und ROADMAP zitieren Dateien, die gelöscht oder nie geschrieben wurden. „Korrigiere“ sie nicht.

4. Überprüfe, ob die Zitate noch aufgelöst werden können

~/.claude/skills/docs-update/scripts/docscheck.py links

Zwei Arten:

• kind=link – ein relativer Markdown-Link, dessen Ziel verschwunden ist. Immer ein echtes Problem.
• kind=source – ein Inline-Code-Pfad, der nicht mehr existiert, meist weil die Datei verschoben oder umbenannt wurde. Narrative Dokumente sind ausgeschlossen, und geschweifte Klammern, <Platzhalter>, Glob-Muster und git-ignorierte Build-Ausgaben werden herausgefiltert, sodass das, was übrig bleibt, einen Blick wert ist.

Korrigiere, was im Umfang liegt. Funde an anderer Stelle im Repo sind es wert, gemeldet zu werden, aber erweitere die Aufgabe nicht stillschweigend zu einem vollständigen Durchlauf.

5. Schreiben

Entschlacke alles, was du schreibst

Wende das unslop-Skill auf jede Zeile an, die du hinzufügst oder änderst. Dokumentation ist der Ort, an dem Geschwafel den größten Schaden anrichtet: Sie wird von Menschen gelesen, die etwas lernen wollen, sie ist das Erste, was ein Neuling sieht, und anders als eine Chat-Nachricht bleibt sie bestehen.

Die Anzeichen, die speziell in Dokumenten auftauchen:

• Halsfreie Einleitungen. „Dieses Dokument bietet einen Überblick über...“, „In diesem Abschnitt werden wir untersuchen...“. Lösche sie und beginne mit der Tatsache.
• Den Code in Prosa wiederholen. „Die Funktion getUser ruft einen Benutzer ab.“ Wenn der Satz der umschriebene Bezeichner auf Deutsch ist, ist er nichts wert. Schreibe den Teil, den der Code nicht sagen kann: die Einschränkung, das Warum, die Stolperfalle.
• Leere Verstärker: umfassend, robust, nahtlos, leistungsstark, flexibel, einfach, leicht, nur. „Führe einfach X aus“ ist falsch, wenn X nicht einfach ist.
• Absicherungen, wo die Antwort eindeutig ist: „im Allgemeinen“, „typischerweise“, „sollte normalerweise“. Entweder es tut es, oder es hängt von etwas ab, das benennbar ist – benenne es.
• Beachte-dass-Füllsel: „Es ist wichtig zu beachten, dass“, „Bitte beachten Sie“, „Denken Sie daran“. Der Satz danach ist der Inhalt; liefere den aus.
• Zusammenfassungsabschnitte, die die Seite darüber zusammenfassen. Wenn das Dokument eine Wiederholung braucht, ist es zu lang.
• Beschreibungsspalten, die den Namen wiederholen. Eine Tabellenzeile | --verbose | Aktiviert die ausführliche Ausgabe | kostet eine Zeile und lehrt nichts.
• Dreierregel-Füllmaterial – ein drittes Beispiel, das eher aus Rhythmusgründen hinzugefügt wurde, als weil es sich von den ersten beiden unterscheidet.

Passe dich der Datei an, nicht dem Geschwafel

Passe dich der bestehenden Stimme der Datei an: ihrer Zeitform, ihrer Dichte, ob Einträge Einzeiler oder Prosa sind. Ein Dokument, in dem ein Abschnitt plötzlich anders klingt, ist schlimmer als eines, das durchgängig knapp ist.

Diese beiden Regeln kollidieren nur, wenn das bestehende Dokument selbst schlampig ist. Dann: Passe dich seiner Struktur und Dichte an, nicht seiner Füllsel, und schreibe keine Abschnitte um, die du nicht anderweitig berührt hast. Ein Dokumenten-Update, das gleichzeitig die gesamte Datei umstilisiert, ist ein nicht überprüfbarer Diff, und es vergräbt die Änderung, die eigentlich wichtig war. Wenn ein Dokument eine gründliche Überarbeitung der Prosa benötigt, sage das und biete es als eigene Aufgabe an.

Der Rest

• Verlinke Quellpfade, anstatt Code in Prosa wiederzugeben, damit die nächste Änderung den Link zerbricht, anstatt die Prosa stillschweigend zu widersprechen.
• Beschreibe, was jetzt wahr ist, im Präsens. Dokumente sind kein Changelog: „wir haben X durch Y ersetzt“ gehört in das CHANGELOG, „das System verwendet Y“ in das Dokument.
• Wenn ein Dokument einen „zuletzt aktualisiert“-Marker hat, verschiebe ihn.

6. Berichte

• den verwendeten Umfang und warum dieser
• aktualisierte Dokumente und was sich in jedem geändert hat
• geprüfte und bewusst unverändert gelassene Dokumente
• defekte Links oder Zitate außerhalb des Umfangs, aufgelistet, aber nicht korrigiert
• alles, was du ohne den Benutzer nicht beurteilen konntest