diodesign/diosix-agent-skills

Documenter Diosix

Chaque page de documentation dans docs/ et README.md doit rester synchronisée à 100 % avec l'implémentation dans hypervisor/, tools/, et scripts/, et doit se conformer à docs/style-guide.md pour que la documentation passe reviewing-diosix du premier coup.

Exigences fondamentales

1. Prose anglaise claire et correcte (prérequis de base) : Toute documentation doit être rédigée en anglais américain avec une orthographe vérifiée, une grammaire solide et un langage concis qui ne sacrifie jamais la clarté technique ni la précision.
2. Vérité dans la documentation : Ne laissez jamais d'anciens indicateurs CLI, d'identifiants de fonction SBI, de numéros ioctl, de dispositions de structure C (uint64_t vs unsigned long), de chemins de fichiers ou de clés de configuration obsolètes dans docs/. Chaque modification de code qui modifie le comportement, les options CLI, les chemins de fichiers modulaires ou les schémas de configuration doit mettre à jour docs/ dans la même modification.
3. Conception pour double public : S'adresser explicitement à deux publics distincts :
   • Utilisateurs (débutants et experts) : Opérateurs démarrant Diosix, exécutant la visite guidée, lançant des machines invitées avec dsx, ou configurant des manifestes déclaratifs système/charte.
   • Développeurs et mainteneurs : Ingénieurs construisant, testant, déboguant et étendant l'hyperviseur M-mode, le dynarec S-mode et les outils U-mode.
4. Conformité stricte au style (docs/style-guide.md) :
   • Limiter la prose, les éléments de liste et les blocs de code à <= 80 caractères par ligne (à l'exclusion des lignes de tableau markdown et des longues URL). Utiliser les noms de base de fichiers dans le texte des liens markdown ([S50dropbear](../tools/.../S50dropbear)) pour que les lignes de lien s'enroulent correctement à 80 colonnes.
   • Utiliser la voix active et le présent ("L'hyperviseur valide le GPA", jamais "Le GPA sera validé par l'hyperviseur").
   • Utiliser des titres en casse de phrase (## Modèle hiérarchique d'invité, jamais ## Modèle Hiérarchique d'Invité).
   • Épeler les abréviations à la première utilisation par page (Interface binaire superviseur (SBI)), puis utiliser uniquement l'abréviation (SBI) par la suite.
   • Utiliser les listes numérotées strictement pour les procédures séquentielles en plusieurs étapes et les listes à puces pour les éléments non séquentiels.
5. En cas de doute, s'arrêter et demander au mainteneur principal : Si le comportement prévu, la terminologie ou la portée du public est ambigu, s'arrêter et demander des éclaircissements au mainteneur principal plutôt que de deviner ou d'inventer des détails.

Guides de référence ciblés

Lire le fichier de référence pertinent avant de rédiger ou de modifier la documentation :

• Style et terminologie canonique : Normes de grammaire/orthographe anglaise, wrapping à 80 colonnes, règles d'expansion des abréviations et définitions canoniques du matériel/de la virtualisation (Machine de construction hôte, Matériel hôte, Plateforme cible, HPA, GPA, GVA, CID).
• Doubles publics et carte des documents : Adaptation du contenu pour les utilisateurs débutants/experts par rapport aux mainteneurs, mappage des modifications de code à des fichiers docs/*.md spécifiques et documentation des conventions de test.