openclaw-refactor-docs

OpenClaw Refactor Docs

Übersicht

Verwende diesen Skill, wenn der Benutzer eine OpenClaw-Dokumentationsseite angibt und darum bittet, diese umzuschreiben, umzugestalten, neu zu organisieren, aufzuteilen, zu kürzen oder zu verbessern.

Dieser Skill baut auf technical-documentation auf: Verwende diesen Skill für Stil, Seitentypen, Struktur, Beispiele, Auffindbarkeit und Verifikation. Dieser Skill fügt den Umschreib-Workflow hinzu, der erforderlich ist, um während einer größeren Dokumentationsumstrukturierung kein korrektes Verhalten zu verlieren.

Eingaben

Erforderlich:

• Ein Pfad zur Ziel-Dokumentationsseite, z. B. docs/plugins/codex-harness.md.

Optional:

• Gewünschter Seitentyp, z. B. Themenseite, Leitfaden, Referenz oder Fehlerbehebung.
• Spezifische Ziele, wie kürzere Hauptseite, Details auf Referenzseiten verschieben oder an aktuelles CLI-Verhalten anpassen.
• Zugehörige Quelldateien, Schemata, Befehle, Tests, Spezifikationen oder PRs.

Wenn die Zielseite fehlt oder mehrdeutig ist, stelle vor der Bearbeitung eine präzise Frage. Andernfalls fahre fort.

Arbeitsvertrag

Gestalte die Zielseite so um, dass sie im angegebenen Umfang nützlicher, prägnanter und umfassender wird.

Behandle eine Umschreibung nicht als Erlaubnis, Verhaltensfakten zu verwerfen. Vorhandenes Material bewahren, überprüfen, verschieben oder explizit zurückziehen. Falsche Dokumentation ist schlimmer als ausführliche Dokumentation.

Bevorzuge diese Aufteilung:

• Themen- oder Leitfadenseiten decken den 80/20-Pfad ab, Entscheidungen, die der Leser treffen muss, sichere Einrichtung, kleinste zuverlässige Verifikation, häufige Fehler und weiterführende Links.
• Referenzseiten decken erschöpfende Felder, Standardwerte, Aufzählungen, Grenzen, Rangfolgeregeln, API-Verträge, enge Interna und seltene Debugging-Details ab.
• Fehlerbehebungsseiten beginnen mit beobachtbaren Symptomen und führen zu Überprüfungen, Ursachen und Lösungen.

Arbeitsablauf

1. Dokumentationsstandard laden

Lese zuerst ../technical-documentation/SKILL.md. Wende dessen Anleitung zu Seitentyp, Stil, Beispielen, Navigation und Verifikation während der gesamten Umstrukturierung an.

Führe pnpm docs:list aus, wenn verfügbar, und lese dann nur die Zielseite sowie die wahrscheinlichen Einstiegspunkte, Referenzen oder zugehörigen Seiten, die für die Umstrukturierung benötigt werden.

2. Seite klassifizieren

Entscheide vor der Bearbeitung den beabsichtigten Seitentyp aus technical-documentation.

Wenn die aktuelle Seite Seitentypen mischt, wähle den Hauptseitentyp und plane, wohin das andere Material gehört:

• Verschiebe erschöpfende Verträge auf eine vorhandene oder neue Referenzseite.
• Verschiebe symptomgesteuertes Material auf eine vorhandene oder neue Fehlerbehebungsseite.
• Verschiebe enge Einrichtungsworkflows in einen Leitfaden, wenn sie den Hauptpfad unterbrechen.
• Behalte präzise Routing-, Entscheidungs- und Sicherheitsdetails auf der Hauptseite, wenn Leser sie benötigen, um den Workflow abzuschließen.

3. Vorhandene Fakten erhalten und prüfen

Erstelle ein Arbeitsinventar aus der alten Seite vor dem Umschreiben. Enthalten sind:

• Konfigurationsfelder, Flags, Befehle, Slash-Befehle, Umgebungsvariablen, Standardwerte, Aufzählungen, Null-Werte und Einschränkungen.
• Rangfolgeregeln, Fallback-Verhalten, Obergrenzen, Limits, Ratenlimits, Timeouts, Lebenszykluszustände, Warteschlangenverhalten und Kompatibilitätsregeln.
• Authentifizierung-, Berechtigungen-, Genehmigungs-, Sandbox-, Sicherheits-, Datenschutz- und zerstörerische Aktionsverhalten.
• Einrichtungsanforderungen, unterstützte Versionen, Abhängigkeiten, Betriebssysteme, Anmeldeinformationen und Kontenanforderungen.
• Fehlermeldungen, Fehlerbehebungssymptome, Diagnosen und Wiederherstellungsschritte.
• Beispiele, erwartete Ausgabe, Befehlsroutingtabellen und Querverweise.

Wähle für jede Tatsache ein Ergebnis:

• Behalte sie auf der umgestalteten Zielseite.
• Verschiebe sie auf eine bestimmte vorhandene Seite.
• Verschiebe sie auf eine bestimmte neue Seite.
• Lösche sie, weil die aktuelle Quelle beweist, dass sie veraltet oder nicht relevant ist.

Leite keine Standardwerte, Berechtigungen, Richtlinien, Timeout-Verhalten oder Sicherheitshaltung aus Namen oder Absicht ab. Überprüfe sie.

4. Quelle der Wahrheit finden

Verwende für jede verhaltenssensitive Behauptung die nächstgelegene autoritative Quelle:

• Öffentliches Schema, Plugin-Manifest, generierte Konfigurationsdokumentation oder exportierte Typen für Konfigurationsfelder.
• CLI-Implementierung, Slash-Befehlshandler, Hilfetext und Befehlstests für Befehle und Flags.
• Laufzeitquellen und Tests für Lebenszyklus, Warteschlangen, Berechtigungen, Fallback, Timeout und Anbieterverhalten.
• Protokolldokumentation, SDK-Fassaden und Vertragstests für APIs und Plugin-Oberflächen.
• Vorhandene Dokumentation nur als sekundäre Belege, es sei denn, das Ziel ist rein konzeptionell.

Wenn eine Seite eine Referenz verspricht, vergleiche ihre Tabellen mit dem Schema, Manifest, CLI-Hilfe, generierten Dokumenten oder exportierten Typen. Fehlende öffentliche Felder, Standardwerte, Rangfolgeregeln, Obergrenzen oder Nebenwirkungen sind Korrektheitsfehler.

5. Verschobenes Material planen

Wenn Details aus der Zielseite verschoben werden, dokumentiere das Ziel vor der Bearbeitung:

• Vorhandene Seite: Name der Seite und des Abschnitts.
• Neue Seite: Wähle Seitentyp, Slug, Titel, Frontmatter-Zusammenfassung, doc-schema-version: 1 und read_when-Hinweise.
• Zielseite: Behalte eine kurze Zusammenfassung und einen Link von der Stelle, an der der Leser die tieferen Details benötigt.

Vermeide doppelte Wahrheit. Wenn derselbe Vertrag an mehreren Stellen erscheint, wähle eine kanonische Seite und verlinke darauf.

6. Umschreiben

Schreibe in dieser Reihenfolge um:

1. Sorge auf dem ersten Bildschirm dafür, dass beantwortet wird, was der Leser tun kann und warum diese Seite existiert.
2. Setze den empfohlenen Pfad vor Alternativen.
3. Behalte nur Entscheidungsfindung und allgemeine betriebliche Details im Hauptfluss.
4. Verschiebe erschöpfende Tabellen und seltene Details auf die geplanten Referenzseiten.
5. Behalte präzise Routingtabellen, wenn sie dem Leser helfen, Befehle, Konfigurationspfade, Harnesse, Plugins, Anbieter oder Referenzen auszuwählen.
6. Füge Fehlerbehebung aus beobachtbaren Symptomen hinzu, nicht aus internen Vermutungen.
7. Verlinke verwandte Konzepte, Leitfäden, Referenzen, Diagnosen und angrenzende Werkzeuge.

Füge doc-schema-version: 1 zum YAML-Frontmatter jeder Dokumentationsseite hinzu, die die Umstrukturierung migriert, erstellt oder wesentlich umschreibt. Wende es nur auf Dokumentationsseitendateien an, nicht auf docs.json oder andere Nicht-Seiten-Metadaten. Wenn eine migrierte Seite generiert wird, aktualisiere den Generator, sodass die Regeneration den Marker beibehält, anstatt generierte Ausgabe manuell zu bearbeiten.

Hinterlasse keine Platzhalter wie "TODO", "TBD" oder "siehe Doku", es sei denn, der Benutzer bittet explizit um einen Entwurf.

7. Alte und neue Seite vergleichen

Vergleiche nach der Bearbeitung die alte und neue Seite:

• Bestätige, dass alle verhaltenssensitiven Fakten erhalten, verschoben oder absichtlich mit quellgestützter Begründung gelöscht wurden.
• Überprüfe, ob die Hauptseite das 80/20-Szenario von Anfang bis Ende abdeckt.
• Überprüfe, ob Referenzseiten für den beanspruchten Umfang erschöpfend bleiben.
• Überprüfe, ob Links von der Zielseite zu den verschobenen Details führen.
• Überprüfe, ob Überschriften stabil, durchsuchbar und handlungsorientiert sind.

Wenn die Umstrukturierung absichtlich relevantes Material entfernt, gib im Abschlussbericht an, wohin es verschoben wurde oder warum es entfernt wurde.

8. Verifizieren

Führe die kleinsten zuverlässigen Dokumentationsprüfungen für die betroffene Oberfläche durch:

• pnpm docs:list
• git diff --check -- <betroffene-Dateien>
• Gezielte pnpm exec oxfmt --check --threads=1 <betroffene-Dateien>
• pnpm docs:check-mdx
• pnpm docs:check-links
• Generierte Dokumentationsprüfungen, wenn Schemata, generierte Konfigurationsdokumente, API-Dokumente oder generierte Baselines betroffen sind

Führe Befehle und Beispiele aus der Seite aus, wann immer möglich. Wenn du eine verhaltenssensitive Behauptung nicht überprüfen kannst, entferne entweder die Behauptung, markiere die Unsicherheit im Fortschrittsbericht oder frage nach der fehlenden Quelle.

Abschlussbericht

Berichte:

• Was hat sich auf der Zielseite geändert.
• Welche Details wurden verschoben und ihre Zielseiten.
• Welche Quellen-der-Wahrheit-Prüfungen haben verhaltenssensitive Behauptungen untermauert.
• Welche Validierung wurde durchgeführt und was aus nicht zusammenhängenden Gründen fehlgeschlagen ist.

Füge kein langes Umschreib-Tagebuch hinzu. Führe nur verbleibende Risiken auf, falls vorhanden.