Documentação Técnica

AÇÃO NECESSÁRIA (Execute imediatamente após a leitura)

1. NOW: Confirme se a tarefa atual se enquadra no escopo desta skill.
2. NOW: Leia ../tool-index.md, valide a disponibilidade e o caminho real da ferramenta.
3. NEXT: Chame o bootstrap quando a ferramenta estiver faltando, não adivinhe o caminho.
4. ACT: Entre na primeira etapa do "Fluxo de Trabalho" e execute, não permaneça no estado de confirmação.

Para orientação sobre estilo de escrita, tom e voz, use Skill(ce:writer) com a persona The Engineer.

Saída de Documentação de Tarefas de Segurança/Reversão

Quando as tarefas de reversão/penetração/CTF/análise de segurança forem concluídas, esta skill será responsável por gerar a documentação técnica formal no diretório de projetos do usuário.

Gatilhos

1. Tarefa de reversão concluída, com conclusões principais produzidas (recuperação de algoritmo, quebra de assinatura, solução de bypass, etc.).
2. Teste de penetração concluído, com vulnerabilidades descobertas e verificadas.
3. Desafio CTF resolvido, com o flag obtido.
4. O usuário solicitou explicitamente "escrever um relatório/documento/writeup".

Seleção de Modelo

Estrutura de Relatório de Fornecedor (Issue #65)

Relatórios formais de segurança DEVEM ler references/vendor-report-rules.md (apenas a estrutura, não copiar o texto original do fornecedor). Selecione o sabor do fornecedor apenas quando as evidências da tarefa ou a solicitação explícita do usuário o exigirem; use flavor = null para reversão comum e outras tarefas.

Princípio: Modelos em essência, não em quantidade — Apenas 2 sabores completos de fornecedor; vuln é apenas um overlay fino opcional, não crie um terceiro modelo completo padrão. Efetivo simultaneamente com §0 Evidência→Descoberta→Caminho; em caso de conflito, o contrato de Evidência tem prioridade.

Especificações de Saída

• Local de Saída: Diretório do projeto atual do usuário (não o diretório do pacote da skill).
• Formato do Nome do Arquivo: YYYY-MM-DD_[类型]-[目标简称]-report.md
• Se o projeto tiver um diretório docs/: Priorize colocá-lo em docs/.
• Codificação: UTF-8
• Idioma: Siga o idioma de diálogo do usuário (relatórios em chinês para diálogos em chinês, relatórios em inglês para diálogos em inglês).

Requisitos de Qualidade

• Todos os blocos de código devem ser executáveis diretamente ou ter contexto claro.
• Não deve haver placeholders/TODOs.
• Descobertas críticas devem ser apoiadas por evidências.
• Passos de reprodução devem permitir que terceiros os reproduzam independentemente.
• Informações sensíveis (tokens reais, senhas, URLs internas) devem ser substituídas por placeholders.
• DEVE incluir a cadeia Evidência → Descoberta → Caminho (ver ../ops/evidence-finding-path.md e o modelo §0).
• DEVE ler references/vendor-report-rules.md: Selecione malware / apt ou flavor = null (tarefas de vulnerabilidade podem ter thin vuln sobreposto); sem sabor, produza apenas o modelo de tarefa original e os elementos Base aplicáveis, sem forçar IOC/ATT&CK.
• DEVE citar os casos scope.md / timeline.md (../scripts/case-init.ps1).

Integração de Gráficos

Ao gerar relatórios, chame a skill diagram-generator para gerar gráficos visuais em locais apropriados:

Os gráficos são incorporados ao markdown do relatório como blocos de código Mermaid, garantindo que possam ser renderizados diretamente no GitHub/GitLab.

Princípios Fundamentais

1. Divulgação Progressiva

Revele informações em camadas:

Avisos, alterações drásticas e pré-requisitos vão no TOPO.

2. Escrita Orientada a Tarefas

<!-- Bad: Feature-oriented -->
## AuthService Class
The AuthService class provides authentication methods...

<!-- Good: Task-oriented -->
## Authenticating Users
To authenticate a user, call login() with credentials:

3. Mostre, Não Conte

Todo conceito precisa de um exemplo concreto.

Padrões de Formatação

• Títulos em minúsculas: "Começando" em vez de "Começando"
• Máximo de 3 níveis de título: Mais profundo significa dividir o documento
• Sempre especifique o idioma em blocos de código
• Caminhos relativos para links internos
• Tabelas para dados estruturados com 3+ atributos

Checklist de Qualidade

• Exemplos de código testados e executáveis
• Sem texto de placeholder ou TODOs
• Corresponde ao comportamento real do código
• Escaneável sem ler tudo
• O leitor sabe o que fazer a seguir

Antí-Padrões

Modelos

Para modelos de README, endpoints de API e organização de arquivos, consulte references/templates.md.

Skills Relacionadas

• Skill(ce:writer) - Estilo de escrita, tom e voz (carregar a persona The Engineer)

…