diodesign/diosix-agent-skills

Documentando o Diosix

Cada página de documentação em docs/ e README.md deve permanecer 100% sincronizada com a implementação em hypervisor/, tools/ e scripts/, e deve estar em conformidade com docs/style-guide.md para que a documentação passe na revisão reviewing-diosix na primeira tentativa.

Mandatos Principais

1. Prosa Clara e Correta em Inglês (Padrão Mínimo): Toda documentação deve ser escrita em inglês americano com ortografia verificada, gramática sólida e redação concisa que nunca sacrifique clareza ou precisão técnica.
2. Verdade na Documentação: Nunca deixe flags de CLI desatualizadas, IDs de função SBI, números ioctl, layouts de structs C (uint64_t vs unsigned long), caminhos de arquivo ou chaves de configuração em docs/. Toda mudança de código que altere comportamento, opções de CLI, caminhos modulares de arquivo ou esquemas de configuração deve atualizar docs/ na mesma alteração.
3. Design para Público Duplo: Atenda explicitamente a dois públicos distintos:
   • Usuários (Iniciantes e Especialistas): Operadores que inicializam o Diosix, executam o tour guiado, iniciam VMs convidadas com dsx ou configuram manifestos declarativos de sistema/carta.
   • Desenvolvedores e Mantenedores: Engenheiros que constroem, testam, depuram e estendem o hipervisor em modo M, o dynarec em modo S e as ferramentas em modo U.
4. Conformidade Estrita com o Guia de Estilo (docs/style-guide.md) :
   • Quebre prosa, itens de lista e blocos de código em <= 80 caracteres por linha (excluindo linhas de tabela markdown e URLs longas). Use nomes base de arquivo em texto de link markdown ([S50dropbear](../tools/.../S50dropbear)) para que as linhas de link sejam quebradas corretamente dentro de 80 colunas.
   • Use voz ativa e tempo presente ("O hipervisor valida o GPA," nunca "O GPA será validado pelo hipervisor").
   • Use títulos em letra minúscula (## Modelo de máquina convidada hierárquico, nunca ## Modelo de Máquina Convidada Hierárquico).
   • Escreva abreviações por extenso no primeiro uso por página (Supervisor Binary Interface (SBI)), depois use apenas a abreviação (SBI) daí em diante.
   • Use listas numeradas estritamente para procedimentos sequenciais de várias etapas e listas com marcadores para itens não sequenciais.
5. Quando Não Tiver Certeza, Pare e Pergunte ao Mantenedor Líder: Se o comportamento pretendido, terminologia ou escopo do público for ambíguo, pare e pergunte ao mantenedor líder para esclarecimentos, em vez de adivinhar ou inventar detalhes.

Guias de Referência Focados

Leia o arquivo de referência relevante antes de redigir ou editar documentação:

• Estilo e Terminologia Canônica : Padrões de gramática/ortografia em inglês, quebra de linha em 80 colunas, regras de expansão de abreviações e definições canônicas de hardware/virtualização (Máquina de construção host, Hardware host, Plataforma de destino, HPA, GPA, GVA, CID).
• Públicos Duplos e Mapa de Documentos : Adaptar conteúdo para usuários iniciantes/especialistas vs. mantenedores, mapear mudanças de código para arquivos específicos docs/*.md e documentar convenções de teste. }