.agent/global/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 sugestão de mensagem de commit para o operador humano	global	2026-10-14

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. Sugestão de Mensagem de Commit (Commit Exclusivo por Humano):
   • O agente NUNCA executa git commit ou git push na aplicação (<base_projeto>) nem na Wiki (<modulo-wiki>).
   • Ao finalizar, apresenta ao operador humano a sugestão de mensagem de commit pronta para copiar: 💬 Sugestão de Commit: docs(<modulo-id>): <descrição sucinta das alterações>

---

🏛️ 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) + sugestão de commit
/documentacao wiki-usuario <modulo>

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

# Criar um ADR na Wiki Dev + sugestão de commit
/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 aplicação ou na Wiki (<base_projeto>/../wiki) não deve executar git commit nem git push, apresentando ao final apenas a sugestão de mensagem de commit para o operador humano.

---

🔒 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 (Commit Exclusivo por Humano): É proibido à IA executar git commit ou git push na aplicação principal (<base_projeto>) e na Wiki (<modulo-wiki>). A IA deve apenas sugerir o texto do commit (docs(<modulo-id>): ...) para o operador humano. Apenas o submódulo .agent pode receber commit/push automático (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.