.agent/global/workflows/documentacao.md

type	name	description	scope	updatedAt
workflow	documentacao	Acionar o Agente de Documentação para documentar o contexto do chat ou executar comandos específicos nos 6 pilares com versionamento automático na Wiki	global	2026-09-05

Workflow: /documentacao (Agente de Documentação & Memória)

Este workflow aciona o Agente de Documentação para gerar, atualizar ou auditar a documentação nos 6 pilares canônicos do Documentation-Driven Development (DDD).

---

⚡ Comportamento Padrão (Sem Instruções Adicionais)

Quando invocado como /documentacao (ou /doc) sem nenhum parâmetro, o agente executa automaticamente a Documentação Contextual Baseada no Chat:

1. Varredura Integral do Contexto:
   • Analisa todo o histórico da conversa, arquivos editados (git status), decisões tomadas e regras implementadas.
2. Distribuição e Geração nos 6 Pilares:
   • Pilar 1 (Código-Fonte): Insere JSDoc de aplicação prática nos arquivos alterados na sessão (rules/jsdoc-padrao.md).
   • Pilar 2 (Ajuda UI): Gera {componente}.ajuda.md para modais e telas criados/modificados (skills/adicionar-ajuda).
   • Pilar 3 (Wiki Usuário): Atualiza manuais em <base_projeto>/../wiki/<modulo>/ se houver mudanças com impacto no usuário final.
   • Pilar 4 (Wiki Dev): Documenta regras técnicas ({modulo}.regras-negocio.md) e ADRs em <base_projeto>/../wiki/dev/<modulo>/.
   • Pilar 5 (Rota IA): Assegura que novos schemas e rotas estejam refletidos na rota /llm.md.
   • Pilar 6 (Memória IA): Registra o relatório completo da sessão no arquivo dedicado <base_projeto>/memorias-ia/sessao-AAAA-MM-DD-slug.md e indexa a alteração no arquivo central <base_projeto>/memorias-ia/historico-acoes.md inserindo linha na tabela com as colunas: Data | Memória / Ação | Arquivo Memoria | Citações no Código-Fonte.
3. 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
     

   • Fronteira Inegociável da Aplicação: Na aplicação principal (<base_projeto>), o agente NÃO pode mexer no git (o versionamento do código-fonte da aplicação permanece sob controle humano exclusivo).
4. Entrega de Relatório:
   • Apresenta um resumo claro ao operador de tudo o que foi documentado com links diretos para os arquivos gerados e confirmação do push na Wiki.

---

🏛️ Os 6 Pilares Canônicos

Pilar	Escopo / Destino	O que é gerado/auditado
1. Código-Fonte	.ts, .vue, .js	JSDoc e comentários claros quanto à aplicação prática (ver rules/jsdoc-padrao.md).
2. Ajuda na Tela	*-front/.../{componente}.ajuda.md	Ajuda contextual co-localizada: para modalX.vue \rightarrow modalX.ajuda.md.
3. Wiki do Usuário	<base_projeto>/../wiki/<modulo>/	Aplicação VitePress com acesso dos usuários (manuais, tutoriais e fluxos).
4. Wiki de Desenvolvimento	<base_projeto>/../wiki/dev/<modulo>/	Aplicação VitePress com acesso interno dev: regras de negócio ({modulo}.regras-negocio.md), modelos de banco, arquitetura e ADRs (adrs/).
5. Integração de IA	Rota Backend /llm.md	Catálogo de schemas Zod, enums e contratos para consumo por LLMs.
6. Memória da IA	<base_projeto>/memorias-ia/	modulo.yml (identidade), índice historico-acoes.md (Data | Memória / Ação | Arquivo Memoria | Citações no Código-Fonte) e memórias de sessão 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>"

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).