docs-generator

Documentação Técnica

AÇÃO REQUERIDA (leia e execute imediatamente)

1. AGORA: Confirme se a tarefa atual se enquadra no escopo deste skill
2. AGORA: Leia ../tool-index.md e valide a disponibilidade e o caminho real das ferramentas
3. PRÓXIMO: Se faltar ferramentas, chame o bootstrap — não adivinhe caminhos
4. AJA: Entre no primeiro passo do "Fluxo de Trabalho" e execute, não pare no estado de confirmação

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

Saída de Documentos para Tarefas de Segurança/Reversa

Quando uma tarefa de engenharia reversa, penetração, CTF ou análise de segurança for concluída, este skill é responsável por gerar a documentação técnica formal no diretório do projeto do usuário.

Momento de Ativação

1. Tarefa de engenharia reversa concluída, com conclusões principais (algoritmo recuperado, assinatura quebrada, esquema de bypass etc.)
2. Teste de penetração concluído, com vulnerabilidades descobertas e validadas
3. Desafio CTF resolvido, flag obtida
4. Usuário solicita explicitamente "escrever um relatório/documento/writeup"

Seleção de Template

Tipo de Tarefa	Template a Usar
Reversa APK/binário/so	references/security-report-templates.md → Relatório de Engenharia Reversa
Teste de Penetração/Descoberta de Vulnerabilidades	references/security-report-templates.md → Relatório de Penetração
Solução de CTF	references/security-report-templates.md → Writeup CTF
Reversa de Assinatura JS/Web	references/security-report-templates.md → Relatório de Reversa de Assinatura
Malware / APT / Análise de Vírus	references/security-report-templates.md + references/vendor-report-rules.md
Documentação Técnica Geral	references/templates.md → README / Documentação de API

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

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

Flavor / Overlay	Quando Usar	Esqueleto de Referência Principal
malware	Amostra maliciosa clara, trojan, cavalo de Troia, phishing com envenenamento	Estilo Huorong: Visão Geral → Fluxo → Análise de Amostra → Resposta a Incidentes → IOC
apt	APT/campanha/grupo/cadeia de infecção multi-estágio/ direcionamento setorial	Estilo Kaspersky Securelist: Resumo → Cadeia de Infecção → Narrativa de Investigação → Descobertas Interessantes → Análise Técnica → Detecção e Mitigação → IOC
flavor = null	Reversa comum de APK/ELF/PE/Mach-O, análise de algoritmo/firmware, penetração/CTF/assinatura JS	Template original da tarefa + Elementos Base; não use capítulos exclusivos de malware/APT
thin vuln	Usuário solicita claramente análise técnica de vulnerabilidade/patch/CVE	Visão Geral → Impacto/Reprodução → Análise de Crash e Patch → Recomendações de Proteção (sobreposto em null, não é o terceiro flavor de texto completo padrão)

Princípio: menos é mais nos templates — apenas 2 flavors completos de fornecedores; vuln é apenas um overlay opcional enxuto, sem criar um terceiro conjunto de templates completos. Vigora simultaneamente com §0 Evidência → Descoberta → Caminho; em caso de conflito, o contrato de Evidência prevalece.

Especificações de Saída

• Local de Saída: Diretório atual do projeto do usuário (não o diretório do pacote do skill)
• Formato do Nome do Arquivo: YYYY-MM-DD_[tipo]-[abreviatura-alvo]-report.md
• Se o projeto tiver diretório docs/: Priorize colocá-lo dentro de docs/
• Codificação: UTF-8
• Idioma: Seguir o idioma da conversa do usuário (conversa em chinês → relatório em chinês, conversa em inglês → relatório em inglês)

Requisitos de Qualidade

• Todos os blocos de código devem ser diretamente executáveis ou ter contexto claro
• Sem placeholders/TODO
• Descobertas críticas devem ter suporte de evidências
• Etapas de reprodução devem permitir que terceiros repliquem independentemente
• Informações sensíveis (tokens reais, senhas, URLs internos) devem ser substituídas por placeholders
• DEVE incluir a cadeia Evidência → Descoberta → Caminho (consulte ../ops/evidence-finding-path.md e o template §0)
• DEVE ler references/vendor-report-rules.md: selecione malware/apt ou flavor = null (tarefas de vulnerabilidade podem sobrepor o thin vuln); sem flavor, saia apenas com o template original da tarefa e os elementos Base aplicáveis, sem forçar IOC/ATT&CK
• DEVE referenciar scope.md / timeline.md do caso (../scripts/case-init.ps1)

Integração de Diagramas

Ao gerar o relatório, chame o skill diagram-generator nos locais apropriados para criar diagramas visuais:

Tipo de Relatório	Diagramas Sugeridos	Tipo de Diagrama
Relatório de Engenharia Reversa	Gráfico de chamada de funções, diagrama de fluxo de dados	Mermaid flowchart / sequenceDiagram
Relatório de Teste de Penetração	Caminho de ataque, topologia de rede	Mermaid flowchart / Graphviz
Writeup CTF	Fluxograma de raciocínio da solução	Mermaid flowchart
Relatório de Reversa de Assinatura JS	Diagrama de sequência da cadeia de requisições, fluxograma do algoritmo	Mermaid sequenceDiagram / flowchart

Incorpore os diagramas como blocos de código Mermaid no Markdown do relatório, garantindo renderização direta no GitHub/GitLab.

---

Princípios Fundamentais

1. Divulgação Progressiva

Revele as informações em camadas:

Camada	Conteúdo	Pergunta do Usuário
1	Descrição de uma frase	O que é?
2	Bloco de código de início rápido	Como uso?
3	Referência completa da API	Quais são minhas opções?
4	Análise aprofundada da arquitetura	Como funciona?

Avisos, mudanças que quebram compatibilidade e pré-requisitos vão no TOPO.

2. Escrita Orientada a Tarefas

<!-- Ruim: Orientado a recurso -->
## Classe AuthService
A classe AuthService fornece métodos de autenticação...

<!-- Bom: Orientado a tarefa -->
## Autenticando Usuários
Para autenticar um usuário, chame login() com as credenciais:

3. Mostre, Não Conte

Cada conceito precisa de um exemplo concreto.

Padrões de Formatação

• Títulos em minúsculas: "Getting started" não "Getting Started" (mantenha o padrão original do documento, mas na tradução use a capitalização adequada para o português — neste contexto, manteremos como "primeiros passos" com minúscula, já que o padrão original em inglês é sentence case)
• Máximo 3 níveis de título: Mais fundo significa dividir o documento
• Sempre especifique a linguagem em blocos de código
• Caminhos relativos para links internos
• Tabelas para dados estruturados com 3 ou mais atributos

Lista de Verificação de Qualidade

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

Anti-Padrões

Problema	Correção
Muralha de texto	Quebre com títulos, marcadores, código, tabelas
Informação crítica enterrada	Avisos/mudanças que quebram no TOPO
Documentação de erro faltando	Sempre documente o que pode dar errado

Templates

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

Skills Relacionados

• Skill(ce:writer) — Estilo de escrita, tom e voz (carregue a persona The Engineer)
• Skill(ce:visualizing-with-mermaid) — Diagramas de arquitetura e fluxo

---

Auto-Bootstrap Sob Demanda

Este skill não depende de ferramentas externas, é puramente geração de texto. Não requer bootstrap.

Se precisar renderizar diagramas incorporados no relatório, chamará o skill diagram-generator/.

---

Contexto de Roteamento

Entrada a montante: Todos os skills de segurança/reversa chamam automaticamente este skill após a conclusão da tarefa Modo de ativação:

• Automático: executado como passo 9 da cadeia de comportamento após conclusão da tarefa
• Manual: usuário diz "escrever relatório", "gerar documentação", "writeup"

Módulos associados no mesmo nível:

• apk-reverse/ — Gera relatório de reversa após conclusão de APK
• ida-reverse/ — Gera relatório de reversa após conclusão de análise binária
• radare2/ — Gera relatório de reversa após conclusão de análise CLI
• js-reverse/ — Gera relatório de assinatura após conclusão de reversa JS
• reverse-engineering/ — Gera relatório de reversa após conclusão de reversa geral
• field-journal/ — O conteúdo do relatório também serve como fonte de dados para o diário de evolução

Template de relatório de segurança: references/security-report-templates.md Regras de relatório de fornecedores: references/vendor-report-rules.md (flavor: malware | apt | null; overlay opcional: vuln) Template de documentação geral: references/templates.md

Auto-Verificação de Conclusão da Tarefa (DEVE ser aprovada antes de declarar conclusão)

• Executei cada passo do fluxo de trabalho (e não apenas li)?
• Usei caminhos reais de ferramentas com base em tool-index?
• Produzi evidências reproduzíveis (comandos/scripts/capturas de tela/relatórios)?
• O relatório contém Evidência / Descoberta / Caminho (contrato ops)?
• Concluí e registrei os itens da Checklist exigidos pelas REGRAS?