openclaw-refactor-docs

OpenClaw Refactor Docs

Présentation

Utilisez cette compétence lorsque l'utilisateur fournit une page de documentation OpenClaw cible et demande de la réécrire, refondre, réorganiser, fractionner, raccourcir ou améliorer.

Cette compétence s'appuie sur technical-documentation : utilisez-la pour le style, les types de pages, la structure, les exemples, la découvrabilité et la vérification. Cette compétence ajoute le workflow de réécriture nécessaire pour éviter de perdre un comportement précis lors d'une refonte importante de la documentation.

Entrées

Requis :

• Un chemin de page de documentation cible, par exemple docs/plugins/codex-harness.md.

Optionnel :

• Type de page souhaité, comme page thématique, guide, référence ou dépannage.
• Objectifs spécifiques, par exemple raccourcir la page principale, déplacer les détails vers des pages de référence, ou aligner sur le comportement actuel de l'interface en ligne de commande.
• Fichiers sources associés, schémas, commandes, tests, spécifications ou PR.

Si la page cible est manquante ou ambiguë, posez une question concise avant d'éditer. Sinon, procédez.

Contrat de travail

Refondez la page cible pour la rendre plus utile, concise et complète dans le cadre de son périmètre défini.

Ne considérez pas une réécriture comme une permission de jeter des faits comportementaux. Préservez, vérifiez, déplacez ou retirez explicitement le contenu existant. Une documentation incorrecte est pire qu'une documentation verbeuse.

Privilégiez cette répartition :

• Les pages thématiques ou guides couvrent le chemin 80/20, les décisions que le lecteur doit prendre, la configuration sûre, la plus petite vérification fiable, les échecs courants et les liens vers d'autres ressources.
• Les pages de référence couvrent les champs exhaustifs, les valeurs par défaut, les énumérations, les limites, les règles de précédence, les contrats API, les détails internes pointus et les rares détails de débogage.
• Les pages de dépannage partent des symptômes observables et mappent aux vérifications, causes et correctifs.

Workflow

1. Charger la norme de documentation

Lisez d'abord ../technical-documentation/SKILL.md. Appliquez ses consignes de type de page, style, exemples, navigation et vérification tout au long de la refonte.

Exécutez pnpm docs:list lorsque disponible, puis lisez uniquement la page cible et les points d'entrée, références ou pages connexes probables nécessaires à la refonte.

2. Classifier la page

Avant d'éditer, décidez du type de page prévu à partir de technical-documentation.

Si la page actuelle mélange les types de pages, choisissez le type de page principal et planifiez où placer l'autre contenu :

• Déplacez les contrats exhaustifs vers une page de référence existante ou nouvelle.
• Déplacez le matériel orienté symptômes vers une page de dépannage existante ou nouvelle.
• Déplacez les workflows de configuration étroits vers un guide lorsqu'ils interrompent le chemin principal.
• Conservez les détails concis de routage, de décision et de sécurité dans la page principale lorsque les lecteurs en ont besoin pour terminer le workflow.

3. Préserver et auditer les faits existants

Créez un inventaire de travail à partir de l'ancienne page avant la réécriture. Incluez :

• Champs de configuration, drapeaux, commandes, commandes slash, variables d'environnement, valeurs par défaut, énumérations, valeurs nullables et contraintes.
• Règles de précédence, comportement de repli, plafonds, limites, limites de débit, délais d'attente, états de cycle de vie, comportement de mise en file d'attente et règles de compatibilité.
• Comportement d'authentification, d'autorisation, d'approbation, de bac à sable, de sécurité, de confidentialité et d'action destructive.
• Exigences de configuration, versions prises en charge, dépendances, systèmes d'exploitation, identifiants et exigences de compte.
• Messages d'erreur, symptômes de dépannage, diagnostics et étapes de récupération.
• Exemples, sortie attendue, tables de routage de commandes et liens croisés.

Pour chaque fait, choisissez un résultat :

• Conservez-le dans la page cible refondue.
• Déplacez-le vers une page existante spécifique.
• Déplacez-le vers une nouvelle page spécifique.
• Supprimez-le car la source actuelle prouve qu'il est obsolète ou hors de portée.

Ne déduisez pas les valeurs par défaut, les permissions, la politique, le comportement de délai d'attente ou la posture de sécurité à partir des noms ou de l'intention. Vérifiez-les.

4. Trouver la source de vérité

Utilisez la source faisant autorité la plus proche pour chaque affirmation sensible au comportement :

• Schéma public, manifeste de plugin, documentation de configuration générée ou types exportés pour les champs de configuration.
• Implémentation de l'interface en ligne de commande, gestionnaires de commandes slash, texte d'aide et tests de commandes pour les commandes et drapeaux.
• Source d'exécution et tests pour le cycle de vie, la mise en file d'attente, les permissions, le repli, le délai d'attente et le comportement du fournisseur.
• Documentation du protocole, façades SDK et tests de contrat pour les API et les surfaces de plugin.
• Documentation existante uniquement comme preuve secondaire, sauf si la cible est purement conceptuelle.

Si une page promet une référence, comparez ses tableaux au schéma, au manifeste, à l'aide de l'interface en ligne de commande, à la documentation générée ou aux types exportés. Les champs publics manquants, les valeurs par défaut, les règles de précédence, les plafonds ou les effets secondaires sont des bugs de correction.

5. Planifier le contenu déplacé

Lorsque vous déplacez des détails hors de la page cible, enregistrez la destination avant d'éditer :

• Page existante : nommez la page et la section.
• Nouvelle page : choisissez le type de page, l'identifiant, le titre, le résumé de l'en-tête, doc-schema-version: 1 et les indices read_when.
• Page cible : conservez un bref résumé et un lien à partir du point où les lecteurs ont besoin des détails plus approfondis.

Évitez les vérités en double. Si le même contrat apparaît à plusieurs endroits, choisissez une page canonique et faites un lien vers elle.

6. Réécrire

Réécrivez dans cet ordre :

1. Faites en sorte que le premier écran réponde à ce que le lecteur peut faire et pourquoi cette page existe.
2. Placez le chemin recommandé avant les alternatives.
3. Ne conservez que les détails opérationnels courants et de prise de décision dans le flux principal.
4. Déplacez les tableaux exhaustifs et les détails rares vers les pages de référence prévues.
5. Conservez les tables de routage concises lorsqu'elles aident les lecteurs à choisir des commandes, des chemins de configuration, des harnais, des plugins, des fournisseurs ou des références.
6. Ajoutez le dépannage à partir de symptômes observables, pas de suppositions internes.
7. Liez les concepts connexes, guides, références, diagnostics et outils adjacents.

Ajoutez doc-schema-version: 1 à l'en-tête YAML de chaque page de documentation que la refonte migre, crée ou réécrit de manière substantielle. Appliquez-le uniquement aux fichiers de page de documentation, pas à docs.json, au glossaire JSON ou à d'autres métadonnées non liées aux pages. Si une page migrée est générée, mettez à jour le générateur afin que la régénération conserve le marqueur au lieu de modifier manuellement la sortie générée.

Ne laissez pas d'espaces réservés tels que « TODO », « TBD » ou « voir documentation » sauf si l'utilisateur demande explicitement un brouillon.

7. Comparer l'ancien et le nouveau

Après l'édition, comparez l'ancienne et la nouvelle page :

• Confirmez que tous les faits sensibles au comportement ont été conservés, déplacés ou intentionnellement supprimés avec une raison basée sur la source.
• Vérifiez que la page principale couvre toujours le scénario 80/20 de bout en bout.
• Vérifiez que les pages de référence restent exhaustives pour le périmètre qu'elles prétendent couvrir.
• Vérifiez que les liens depuis la page cible atteignent les détails déplacés.
• Vérifiez que les titres sont stables, recherchables et orientés action.

Si la refonte supprime délibérément du contenu pertinent, indiquez où il est allé ou pourquoi il a été supprimé dans le rapport final.

8. Vérifier

Exécutez les vérifications de documentation les plus petites et fiables pour la surface touchée :

• pnpm docs:list
• git diff --check -- <fichiers-touchés>
• pnpm exec oxfmt --check --threads=1 <fichiers-touchés> ciblé
• pnpm docs:check-mdx
• pnpm docs:check-links
• pnpm docs:check-i18n-glossary lorsque le texte des liens, la navigation, les étiquettes ou les surfaces du glossaire ont changé
• Vérifications de documentation générée lorsque les schémas, la documentation de configuration générée, la documentation API ou les références générées sont touchés

Exécutez les commandes et les exemples de la page chaque fois que possible. Si vous ne pouvez pas vérifier une affirmation sensible au comportement, soit supprimez l'affirmation, marquez l'incertitude dans le rapport de travail en cours, ou demandez la source manquante.

Rapport final

Rapportez :

• Ce qui a changé dans la page cible.
• Quels détails ont été déplacés et vers quelles pages de destination.
• Quelles vérifications de source de vérité ont étayé les affirmations sensibles au comportement.
• Quelle validation a été exécutée et ce qui a échoué pour des raisons non liées.

N'incluez pas un long journal de réécriture. Ne mentionnez les risques restants que s'il y en a.