diodesign/diosix-agent-skills

Documentando Diosix

Cada página de documentación en docs/ y README.md debe mantenerse 100% sincronizada con la implementación en hypervisor/, tools/ y scripts/, y debe cumplir con docs/style-guide.md para que la documentación pase reviewing-diosix en la primera revisión.

Mandatos principales

1. Prosa en inglés clara y correcta (requisito básico): Toda la documentación debe estar escrita en inglés americano con ortografía verificada, gramática sólida y redacción concisa que nunca sacrifique claridad técnica o precisión.
2. Verdad en la documentación: Nunca dejes flags de CLI obsoletos, IDs de función SBI, números ioctl, diseños de struct C (uint64_t vs unsigned long), rutas de archivo o claves de configuración en docs/. Cada cambio de código que altere comportamiento, opciones de CLI, rutas de archivos modulares o esquemas de configuración debe actualizar docs/ en el mismo cambio.
3. Diseño para dos audiencias: Atiende explícitamente a dos audiencias distintas:
   • Usuarios (principiantes y expertos): Operadores que arrancan Diosix, ejecutan el recorrido guiado, lanzan máquinas virtuales invitadas con dsx o configuran manifiestos declarativos de sistema/carta.
   • Desarrolladores y mantenedores: Ingenieros que construyen, prueban, depuran y extienden el hipervisor en modo máquina (M-mode), el dynarec en modo supervisor (S-mode) y las herramientas en modo usuario (U-mode).
4. Cumplimiento estricto del estilo (docs/style-guide.md):
   • Ajusta la prosa, los elementos de lista y los bloques de código a <= 80 caracteres por línea (excluyendo filas de tablas markdown y URLs largas). Usa nombres base de archivo en el texto de enlaces markdown ([S50dropbear](../tools/.../S50dropbear)) para que las líneas de enlace se ajusten limpiamente dentro de 80 columnas.
   • Usa voz activa y tiempo presente ("El hipervisor valida la GPA", nunca "La GPA será validada por el hipervisor").
   • Usa encabezados en minúscula excepto la primera palabra (## Modelo jerárquico de invitado, nunca ## Modelo Jerárquico de Invitado).
   • Escribe las abreviaturas completas en la primera aparición por página (Interfaz binaria de supervisor (SBI)), luego usa solo la abreviatura (SBI) en adelante.
   • Usa listas numeradas estrictamente para procedimientos secuenciales de varios pasos y listas con viñetas para elementos no secuenciales.
5. Cuando tengas dudas, detente y pregunta al mantenedor principal: Si el comportamiento previsto, la terminología o el alcance de la audiencia son ambiguos, detente y pregunta al mantenedor principal para aclarar, en lugar de adivinar o inventar detalles.

Guías de referencia enfocadas

Lee el archivo de referencia relevante antes de redactar o editar documentación:

• Estilo y terminología canónica: Estándares de gramática/ortografía en inglés, ajuste a 80 columnas, reglas de expansión de abreviaturas y definiciones canónicas de hardware/virtualización (Máquina de compilación anfitriona, Hardware anfitrión, Plataforma objetivo, HPA, GPA, GVA, CID).
• Audiencias duales y mapa de documentos: Adaptación del contenido para usuarios principiantes/expertos versus mantenedores, mapeo de cambios de código a archivos específicos docs/*.md y documentación de convenciones de prueba.