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

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. Sugestão de Mensagem de Commit (Commit Exclusivo por Humano):
   • O agente NUNCA executa git commit ou git push na aplicação principal (<base_projeto>) nem na Wiki (<modulo-wiki>).
   • 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>
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 a sugestão do texto de commit.

---

🏛️ 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) + 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>"

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