otimização do agent para docuemntação

rules/ddd-documentacao-primeiro.md

@@ -1,52 +1,101 @@
 ---
 type: rule
 name: ddd-documentacao-primeiro
-description: Regra global que exige a documentação de novos artefatos antes da implementação (Documentation-Driven Development).
+description: Regra global de Documentation-Driven Development (DDD) definindo os 6 pilares de documentação e memória no ecossistema.
 scope: global
 trigger: always_on
 priority: alta
-updatedAt: "2026-08-12"
+updatedAt: "2026-09-01"
 ---
 
-# Regra: Documentação Obrigatória Antes da Implementação
+# Regra: Documentação Obrigatória Antes da Implementação (DDD)
 
 ## Contexto
-Implementar sem documentar leva ao acúmulo de conhecimento implícito, código inconsistente e perda do conhecimento institucional. Para garantir que as decisões de design, regras de negócio e fluxos estejam claros antes de qualquer código ser escrito, adotamos o Documentation-Driven Development (DDD). A documentação atua como o contrato formal do que será construído.
 
-## Regra
-Antes de implementar qualquer novo artefato (regra, skill, workflow, módulo, endpoint de API, decisão técnica) ou realizar alterações substanciais em artefatos existentes, o agente **DEVE OBRIGATORIAMENTE** criar ou atualizar a documentação na pasta `DOCUMENTACAO/` utilizando o template apropriado da respectiva categoria.
+Implementar sem documentar leva ao acúmulo de conhecimento implícito, código inconsistente e perda de governança. Para garantir que as decisões de arquitetura, regras de negócio, interfaces e integrações estejam claras antes de qualquer código ser escrito, adotamos o **Documentation-Driven Development (DDD)**.
+
+A documentação é a **especificação viva e o contrato formal** do que é construído.
+
+---
+
+## Os 6 Pilares Canônicos de Documentação e Memória
+
+Todo desenvolvimento e manutenção no ecossistema deve obrigatoriamente respeitar a estrutura dos 6 pilares:
+
+| Pilar | Destino / Padrão | Público | Conteúdo Obrigatório |
+| :--- | :--- | :--- | :--- |
+| **1. Código-Fonte** | `.ts`, `.vue`, `.js` | Desenvolvedores / IA | Comentários claros e coerentes quanto à sua aplicação prática, contexto e raciocínio de negócio (JSDoc no topo de funções, serviços e rotas). |
+| **2. Ajuda na Tela (UI)** | `*-front/src/.../{componente}.ajuda.md` | Usuários da UI | Ajuda contextual co-localizada: para `modalX.vue`, o arquivo de ajuda **DEVE** ser `modalX.ajuda.md`. Detalha objetivo, botões, campos e instruções de uso. |
+| **3. Wiki do Usuário** | `../../wiki/<modulo>/` | Usuários / Operadores | Aplicação VitePress com acesso dos usuários. Manuais de operação completos, tutoriais de uso, conceitos de negócio e fluxos da aplicação. |
+| **4. Wiki de Desenvolvimento** | `../../wiki/dev/<modulo>/` | Desenvolvedores / Arquitetos | Aplicação VitePress com acesso interno exclusivo da equipe de desenvolvimento. Arquitetura técnica detalhada, modelos de banco, regras de negócio (`{modulo}.regras-negocio.md`), fluxos de filas (BullMQ), CRONs e ADRs. |
+| **5. Integração de IA** | Rota de Backend `/llm.md` | Agentes de IA / LLMs | Documentação gerada/servida dinamicamente contendo schemas Zod, enums canônicos, endpoints e contratos para consumo por LLMs. |
+| **6. Memória das Ações da IA** | `<base_projeto>/memorias-ia/` | Agentes de IA / Auditoria | Registros de sessões da IA, otimizações executadas, histórico de decisões arquiteturais e relatórios de aprimoramento contínuo. |
+
+> ℹ️ **Estrutura da Wiki VitePress (`../../wiki`)**:
+> - `../../wiki/<modulo>/` $\rightarrow$ Aplicação VitePress voltada ao **acesso dos usuários e clientes**.
+> - `../../wiki/dev/<modulo>/` $\rightarrow$ Seção VitePress de **acesso interno da equipe de desenvolvimento e arquitetura**.
+
+> 🧩 **Polimorfismo do `.agent` e Personalização por Projeto**:
+> O repositório `.agent` é **polimórfico e genérico**, sendo compartilhado entre múltiplos projetos do ecossistema. Toda personalização de cada projeto reside em:
+> - `./memorias-ia/` (na raiz do projeto pai): Registros de ações, sessões e decisões da IA.
+> - `../../wiki/<modulo>/`: Documentação do módulo com acesso dos usuários (VitePress).
+> - `../../wiki/dev/<modulo>/`: Documentação técnica do módulo com acesso interno dev (VitePress).
+
+---
 
 ## Protocolo DDD
 
-Para toda nova demanda ou funcionalidade, siga rigorosamente os passos abaixo:
+Para toda nova demanda, módulo ou funcionalidade, execute os passos abaixo:
 
-1. **Identificar Categoria**: Analisar a demanda e determinar em qual(is) categoria(s) de documentação ela se encaixa (arquitetura, módulos, regras-negócio, contratos, fluxos).
-2. **Consultar Template**: Consultar o respectivo template em `DOCUMENTACAO/<categoria>/_template-*`.
-3. **Criar/Atualizar Documentação**: Redigir a documentação na categoria adequada usando a estrutura do template. Se a funcionalidade altera algo existente, a documentação prévia deve ser atualizada.
-4. **Apresentar ao Operador**: Validar a documentação redigida com o operador (usuário humano) antes de iniciar qualquer código.
-5. **Implementar**: Escrever o código de forma que ele satisfaça e implemente *exatamente* o que foi estabelecido na documentação aprovada.
-6. **Validar**: Testar ou analisar o código para assegurar que ele respeita a especificação em 100%.
-7. **Sincronizar**: Se durante a implementação descobrir-se que ajustes na abordagem são necessários, a documentação deve ser atualizada em sincronia com o código.
+1. **Identificar os Pilares Impactados**:
+   - É alteração de código? $\rightarrow$ Planejar comentários contextuais claros (Pilar 1).
+   - É tela/modal com ajuda ao usuário? $\rightarrow$ Criar/atualizar `modalX.ajuda.md` co-localizado (Pilar 2).
+   - É funcionalidade com impacto no usuário final? $\rightarrow$ Criar/atualizar documentação em `../../wiki/<modulo>/` (Pilar 3).
+   - É componente técnico, arquitetura, serviço ou fila? $\rightarrow$ Criar/atualizar documentação em `../../wiki/dev/<modulo>/` (Pilar 4).
+   - É endpoint, schema ou contrato de API? $\rightarrow$ Assegurar reflexão na rota `/llm.md` (Pilar 5).
+   - É ação estruturante ou otimização de IA? $\rightarrow$ Registrar memória em `<base_projeto>/memorias-ia/` (Pilar 6).
+
+2. **Documentar Antes de Codar**:
+   - Redigir a documentação preliminar nos respectivos destinos e templates antes de iniciar a implementação.
+
+3. **Apresentar ao Operador**:
+   - Validar as especificações e regras com o operador antes de codificar.
+
+4. **Implementar**:
+   - Escrever o código de forma que satisfaça estritamente a documentação validada.
+
+5. **Validar e Sincronizar**:
+   - Se a implementação revelar necessidade de ajustes de design, atualizar a documentação imediatamente para manter 100% de sincronismo.
+
+---
 
 ## Exceções
-Esta regra pode ser ignorada apenas para alterações triviais que não impactam regras de negócio, fluxos ou arquitetura, tais como:
-- Correção de erros de digitação (typos) em arquivos e variáveis.
-- Formatação de código ou linting.
-- Ajustes simples de imports.
-- Continuação de trabalho (ex: a doc já foi feita em um prompt/sessão anterior para esta mesma task).
+
+A etapa de documentação prévia pode ser simplificada apenas para:
+- Correção de typos pontuais.
+- Formatação ou linting sem alteração de lógica.
+- Ajustes triviais de imports.
+
+---
 
 ## Exemplos
 
 ✅ **Correto**:
-- O operador pede um novo endpoint. O agente cria `DOCUMENTACAO/contratos/novo-endpoint` detalhando a API e os schemas usando o template. Após aprovação, cria o código na API.
+- Criou um novo modal `ModalParametros.vue` $\rightarrow$ criou `ModalParametros.ajuda.md` na mesma pasta explicando campos e botões para o usuário.
+- Criou um serviço de cálculo de efluentes $\rightarrow$ inseriu JSDoc claro quanto à sua aplicação prática, documentou a regra técnica em `../../wiki/dev/e-licencie.sigma/` e o guia de uso em `../../wiki/e-licencie.sigma/`.
+- Criou endpoints novos no backend $\rightarrow$ rota `/llm.md` atualizada automaticamente via gerador de contratos.
+- Realizou otimização no ecossistema de agentes $\rightarrow$ registrou relatório em `<base_projeto>/memorias-ia/`.
 
 ❌ **Incorreto**:
-- O operador pede uma nova regra de negócio complexa e o agente já cria a função ou arquivo `.ts` sem antes registrar a regra em `DOCUMENTACAO/regras-negocio/` para validação.
-- O agente toma uma decisão técnica grande (ex: trocar a biblioteca de state management) e apenas implementa no código sem gerar um ADR.
+- Criou `modalX.vue` e colocou ajuda em formato desconhecido ou fora da pasta do componente.
+- Implementou código sem comentários ou com JSDoc que apenas repete os tipos sem explicar a aplicação real no sistema.
+- Criou regras técnicas complexas sem atualizar `../../wiki/dev/<modulo>/`.
+- Gravou registros de ações da IA em pastas despadronizadas fora de `<base_projeto>/memorias-ia/`.
 
-## Impacto
-O código não é mais a fonte da verdade para o funcionamento esperado, mas sim a *implementação* da verdade registrada na documentação. Isso garante rastreabilidade, reduz dependência de memória implícita de sessões passadas e facilita a manutenção por humanos e outras instâncias do agente.
+---
 
 ## Referências
-- `DOCUMENTACAO/README` (Manifesto DDD)
-- Skills relacionadas: `documentar-decisao-tecnica`, `documentar-dominio-modulo`, `documentar-regras-negocio`
+
+- `DOCUMENTACAO/README` (Manifesto DDD e matriz de documentação)
+- Rules: `jsdoc-padrao.md`, `regras-negocio-md.md`, `autonomia-agente.md`
+- Skills: `adicionar-ajuda`, `documentar-dominio-modulo`, `documentar-decisao-tecnica`, `diagnosticar-lacunas-documentacao`