.agent/skills/documentacao/SKILL.md

name	description	scope	updatedAt
documentacao	Acionar o Agente de Documentação & Memória para documentar o contexto da conversa ou gerar artefatos nos 6 pilares canônicos com versionamento automático na Wiki	global	2026-09-05

Skill / Workflow: /documentacao

Esta skill aciona o Agente de Documentação & Memória para gerar, atualizar ou auditar a documentação nos 6 pilares canônicos do Documentation-Driven Development (DDD).

---

⚡ Modo Contextual Padrão (Sem Argumentos)

Ao executar /documentacao (ou /doc) sem nenhum parâmetro, o agente analisa automaticamente todo o histórico do chat, decisões tomadas e arquivos alterados na sessão, gerando e sincronizando a documentação nos pilares afetados:

1. Pilar 1 (Código-Fonte): Insere comentários JSDoc de aplicação prática nos arquivos alterados (rules/jsdoc-padrao.md).
2. Pilar 2 (Ajuda UI): Gera {componente}.ajuda.md para modais e telas criados/modificados (skills/adicionar-ajuda).
3. Pilar 3 (Wiki do Usuário): Atualiza tutoriais e manuais em <base_projeto>/../wiki/<modulo>/ (aplicação VitePress com acesso dos usuários).
4. Pilar 4 (Wiki de Desenvolvimento): Documenta regras de negócio ({modulo}.regras-negocio.md), modelos e ADRs em <base_projeto>/../wiki/dev/<modulo>/ (aplicação VitePress com acesso interno dev).
5. Pilar 5 (Rota IA): Assegura que novos schemas e rotas estejam refletidos na rota /llm.md.
6. Pilar 6 (Memória IA): Registra o relatório completo da sessão no arquivo individual <base_projeto>/memorias-ia/sessao-AAAA-MM-DD-slug.md e atualiza o índice central <base_projeto>/memorias-ia/historico-acoes.md adicionando a linha correspondente na tabela com as colunas: Data | Memória / Ação | Arquivo Memoria | Citações no Código-Fonte.
7. Sincronização Git da Wiki (Obrigatório e Exclusivo):
   • Se houver arquivos novos ou alterados em <base_projeto>/../wiki/:

     git -C <base_projeto>/../wiki add -A
     git -C <base_projeto>/../wiki commit -m "docs(<modulo-id>): sincronizar documentação [contexto]"
     git -C <base_projeto>/../wiki push
     

   • Trava de Segurança da Aplicação: Na aplicação (<base_projeto>), o agente NÃO pode mexer no git (o versionamento do código-fonte da aplicação permanece sob controle humano exclusivo).

---

🏛️ Os 6 Pilares Canônicos

Pilar	Destino / Padrão	Público	Conteúdo Obrigatório
1. Código-Fonte	.ts, .vue, .js	Desenvolvedores / IA	JSDoc e comentários claros quanto à aplicação prática e contexto de negócio.
2. Ajuda na Tela	*-front/.../{componente}.ajuda.md	Usuários da UI	Ajuda contextual co-localizada: para modalX.vue \rightarrow modalX.ajuda.md.
3. Wiki do Usuário	<base_projeto>/../wiki/<modulo>/	Usuários / Clientes	Aplicação VitePress com acesso dos usuários (manuais, tutoriais e fluxos).
4. Wiki de Desenvolvimento	<base_projeto>/../wiki/dev/<modulo>/	Desenvolvedores / Arquitetos	Aplicação VitePress com acesso interno dev: regras de negócio ({modulo}.regras-negocio.md), arquitetura e ADRs (adrs/).
5. Integração de IA	Rota Backend /llm.md	Agentes de IA / LLMs	Catálogo de schemas Zod, enums e contratos para consumo por LLMs.
6. Memória da IA	<base_projeto>/memorias-ia/	Agentes de IA / Auditoria	modulo.yml (identidade), índice historico-acoes.md (Data | Memória / Ação | Arquivo Memoria | Citações no Código-Fonte) e sessões individuais sessao-AAAA-MM-DD-slug.md.

---

🚀 Comandos Específicos (Com Argumentos)

# Diagnosticar lacunas no módulo
/documentacao diagnosticar

# Documentar JSDoc de aplicação prática em arquivo específico
/documentacao jsdoc <caminho/arquivo.ts>

# Criar ajuda contextual modalX.ajuda.md para modal/tela
/documentacao ajuda <caminho/modalX.vue>

# Documentar domínio na Wiki do Usuário (VitePress) + commit/push na wiki
/documentacao wiki-usuario <modulo>

# Documentar regras de negócio na Wiki Dev (VitePress) + commit/push na wiki
/documentacao regras <caminho/servico.ts>

# Criar um ADR na Wiki Dev + commit/push na wiki
/documentacao adr "<Título da Decisão>"

# Upload de arquivo/mídia (PDF, imagem, vídeo) para o MinIO Paiol com link pronto para a Wiki
/documentacao upload <caminho/arquivo.ext> <slug-funcionalidade>

Nota: Qualquer comando que crie ou modifique arquivos na Wiki (<base_projeto>/../wiki) deve finalizar executando git add, git commit, git pull --rebase (resolvendo conflitos na master se houver) e git push diretamente na branch master dentro de ../wiki.

---

🔒 Regras Inegociáveis

1. Nunca inventar regras: Documentar estritamente o que foi implementado no código ou declarado na conversa.
2. Linguagem acessível no usuário: Sem termos técnicos de TI na Wiki do Usuário ou em .ajuda.md.
3. JSDoc de Aplicação: Explicar a utilidade prática no sistema, não apenas repetir tipos.
4. Polimorfismo: O .agent é genérico; personalizações ficam em ./memorias-ia/ e <base_projeto>/../wiki/.
5. Fronteira Git e Gestão em Master na Wiki: Toda atualização em <base_projeto>/../wiki DEVE ser commitada, sincronizada com resolução de conflitos e enviada via git push diretamente na branch master de ../wiki. Na aplicação principal (<base_projeto>), a IA pode comitar apenas em branches de trabalho, sendo proibido comitar na master (ver rules/proibido-commit-ia.md).
6. Mídias e Binários no MinIO Paiol: Arquivos pesados (PDFs, vídeos, imagens e anexos) NUNCA devem ser commitados no Git da Wiki; envie sempre para o MinIO Paiol via ./.agent/scripts/upload-paiol-wiki.sh e versione apenas a URL pública nos arquivos Markdown.