agente documentação

DOCUMENTACAO/README

@@ -8,33 +8,72 @@ updatedAt: "2026-08-12"
 # Documentation-Driven Development (DDD)
 
 ## Manifesto
-No ecossistema Azteca, a documentação precede o código. Nenhum artefato (regra, skill, workflow, módulo, API, decisão técnica) deve ser implementado sem documentação prévia. A documentação é a especificação viva.
+No ecossistema Azteca, a documentação precede o código. Nenhum artefato (regra, skill, workflow, funcionalidade, API, decisão técnica) deve ser implementado sem documentação prévia. A documentação é a especificação viva.
 
 ## Princípios
 1. **Doc First** — Nenhum artefato novo sem documentação prévia.
 2. **Doc como Contrato** — A documentação é a especificação; o código a implementa.
 3. **Código Satisfaz Doc** — Se o código diverge da doc, o código está errado.
 4. **Sincronia Obrigatória** — Mudança no código → atualização da doc; mudança na doc → atualização no código.
-5. **Templates Padronizados** — Cada categoria tem seu template; nenhuma documentação é criada do zero.
-6. **Leitura Antes de Escrita** — Antes de documentar, leia o que já existe.
+5. **Templates Padronizados** — Cada tipo de documento tem seu template centralizado em `_templates/`.
+6. **Co-localização** — Toda documentação de uma funcionalidade fica na pasta daquela funcionalidade.
+7. **Leitura Antes de Escrita** — Antes de documentar, leia o que já existe.
 
-## Categorias de Documentação
+## Organização — Por Funcionalidade
 
-| Categoria | Diretório | O que documenta | Template |
-| :--- | :--- | :--- | :--- |
-| Arquitetura | `DOCUMENTACAO/arquitetura/` | Decisões técnicas e arquiteturais (ADRs) | `_template-adr` |
-| Módulos | `DOCUMENTACAO/modulos/` | Domínio, glossário e entidades de cada módulo | `_template-modulo` |
-| Regras de Negócio | `DOCUMENTACAO/regras-negocio/` | Regras extraídas do código ou definidas pelo operador | `_template-regra` |
-| Contratos | `DOCUMENTACAO/contratos/` | Contratos de API, schemas, endpoints | `_template-contrato` |
-| Fluxos | `DOCUMENTACAO/fluxos/` | Jornadas do usuário e fluxos de uso | `_template-fluxo` |
+A `DOCUMENTACAO/` é organizada por **funcionalidade/domínio funcional** do módulo Qualifica, não por tipo de documento.
+
+### Estrutura
+
+```text
+DOCUMENTACAO/
+├── README.md                              ← Índice geral (público)
+├── funcionalidades/                       ← Subdivisão por funcionalidade
+│   └── <funcionalidade>/                  ← Uma pasta por funcionalidade
+│       ├── especificacao.md               ← Spec técnica (schemas, DDL, componentes)
+│       ├── regras-negocio.md              ← Regras de negócio em linguagem natural
+│       ├── contratos.md                   ← Endpoints de API (quando aplicável)
+│       └── fluxo.md                       ← Fluxograma detalhado (quando aplicável)
+├── _transversais/                         ← ADRs e decisões que cruzam funcionalidades
+│   └── adr-NNN-titulo.md
+└── _templates/                            ← Templates (espelhados de .agent/DOCUMENTACAO/_templates/)
+```
+
+### Funcionalidades do Qualifica
+
+| Funcionalidade | Pasta | Domínio |
+| :--- | :--- | :--- |
+| Avaliações | `funcionalidades/avaliacoes/` | Ciclos de avaliação, envios, análise, preenchimento |
+| Empresas | `funcionalidades/empresas/` | Cadastro, painel, empreendedores, contatos |
+| Formulários | `funcionalidades/formularios/` | Builder, seções, campos, respostas |
+| Contratos Comerciais | `funcionalidades/contratos-comerciais/` | Gestão de contratos |
+| Relatórios | `funcionalidades/relatorios/` | PDFs, histórico, documentos, eventos |
+| Importador | `funcionalidades/importador/` | Importação de dados |
+| Ajuda e Suporte | `funcionalidades/ajuda-suporte/` | Chamados, diagnóstico, suporte contextual |
+| Validade | `funcionalidades/validade/` | Controle de validade |
+
+### Tipos de Documento (dentro de cada funcionalidade)
+
+| Arquivo | Template | Quando criar |
+| :--- | :--- | :--- |
+| `especificacao.md` | `_templates/_template-especificacao` | Sempre — é o doc mínimo de cada funcionalidade |
+| `regras-negocio.md` | `_templates/_template-regras-negocio` | Quando a funcionalidade tem lógica de decisão não-trivial |
+| `contratos.md` | `_templates/_template-contrato` | Quando a funcionalidade expõe endpoints de API |
+| `fluxo.md` | `_templates/_template-fluxo` | Quando a funcionalidade tem ciclo de vida complexo |
+
+### Documentação Transversal
+
+Decisões arquiteturais (ADRs) e documentação que cruza múltiplas funcionalidades ficam em `_transversais/`, usando o template `_templates/_template-adr`.
 
 ## Workflow DDD
 1. **Receber demanda**
-2. **Documentar** (criar/atualizar documentação na categoria apropriada usando o template)
-3. **Revisar** (apresentar a documentação ao operador para validação)
-4. **Implementar** (codificar de acordo com a documentação aprovada)
-5. **Validar** (verificar se o código satisfaz a doc 100%)
-6. **Sincronizar** (atualizar a documentação se a implementação revelou ajustes necessários)
+2. **Identificar funcionalidade** — Determinar a qual funcionalidade a demanda pertence
+3. **Consultar template** — Usar o template adequado de `_templates/`
+4. **Documentar** — Criar/atualizar documentação na pasta da funcionalidade
+5. **Revisar** — Apresentar a documentação ao operador para validação
+6. **Implementar** — Codificar de acordo com a documentação aprovada
+7. **Validar** — Verificar se o código satisfaz a doc 100%
+8. **Sincronizar** — Atualizar a documentação se a implementação revelou ajustes
 
 ## Integração com o Ecossistema
 
@@ -42,7 +81,7 @@ No ecossistema Azteca, a documentação precede o código. Nenhum artefato (regr
 | :--- | :--- |
 | `rules/regras-negocio-md.md` | Define formato e obrigatoriedade de documentar regras de negócio |
 | `skills/documentar-decisao-tecnica` | Fornece habilidade para criar e atualizar ADRs |
-| `skills/documentar-dominio-modulo` | Estrutura para levantar glossário e domínio de módulos |
+| `skills/documentar-dominio-modulo` | Estrutura para levantar glossário e domínio |
 | `skills/documentar-regras-negocio` | Habilidade para extrair e redigir regras |
 | `rules/diagnostico-antes-correcao.md`| Diagnóstico exige leitura e alinhamento com doc antes de corrigir bugs |