.agent/skills/documentar-dominio-modulo/SKILL.md

name	scope	updatedAt	description
documentar-dominio-modulo	global	2026-09-01	Guia para documentar o domínio científico/técnico de cada módulo nas wikis de usuário (<base_projeto>/../wiki/<modulo-id>/) e de desenvolvimento (<base_projeto>/../wiki/dev/<modulo-id>/).

Skill: Documentar Domínio de um Módulo

Use esta skill ao iniciar um novo módulo SaaS ou ao perceber que o agente não conhece o vocabulário e as regras do domínio que o módulo aborda.

Cada módulo opera em uma disciplina diferente da ciência/gestão ambiental (licenciamento, efluentes, bombeamento, resíduos, projetos, etc.). O repositório <modulo-wiki> (configurado em memorias-ia/modulo.yml, com fallback padrão para <base_projeto>/../wiki) é uma aplicação VitePress, onde a base factual do domínio é estruturada em dois níveis de acesso:

1. Wiki do Usuário (<modulo-wiki>/<modulo-id>/): Aplicação VitePress com acesso dos usuários e clientes (linguagem funcional, conceitos, glossário, fluxos e manuais operacionais).
2. Wiki de Desenvolvimento (<modulo-wiki>/dev/<modulo-id>/): Aplicação VitePress com acesso interno exclusivo da equipe de desenvolvimento e arquitetura (arquitetura técnica, diagramas, modelos de banco, regras de negócio e ADRs).

---

PASSO 1 — Identificar a Identidade e Domínio do Módulo via memorias-ia/modulo.yml

Consultar obrigatoriamente <base_projeto>/memorias-ia/modulo.yml na raiz do projeto pai:

• modulo-id: identificador do módulo (ex: e-licencie.sigma)
• modulo-caminho: rota base na URL (ex: /sigma/)
• modulo-descricao: escopo funcional e propósito do módulo
• modulo-tipo: stack tecnológica e arquitetura
• modulo-wiki: caminho relativo ou absoluto para a Wiki (fallback: ../wiki/)

Os destinos canônicos da documentação na aplicação VitePress (<modulo-wiki>) são:

• Wiki do Usuário: <modulo-wiki>/<modulo-id>/
• Wiki de Desenvolvimento: <modulo-wiki>/dev/<modulo-id>/

---

PASSO 2 — Criar Documentação na Wiki do Usuário (<modulo-wiki>/<modulo-id>/)

Estruturar o guia do usuário e conceitos de negócio em linguagem clara e acessível:

# [Nome do Módulo] — Guia do Usuário

## Visão Geral
Breve descrição do propósito do módulo para o gestor e operador.

## Glossário do Domínio
| Termo | Definição | Sigla |
|---|---|---|
| Ponto de Monitoramento | Local físico onde são coletadas amostras | PM |
| Parâmetro Ambiental | Variável físico-química monitorada (ex: DBO, DQO) | — |

## Fluxos Operacionais do Usuário
1. Cadastro de pontos de monitoramento.
2. Lançamento e importação de medições.
3. Emissão de relatórios e acompanhamento de conformidade.

---

PASSO 3 — Criar Documentação na Wiki de Desenvolvimento (<modulo-wiki>/dev/<modulo>/)

Estruturar a especificação técnica, modelos de banco e arquitetura:

# [Nome do Módulo] — Arquitetura e Engenharia

## Modelo de Dados e Entidades
- **Tabelas principais:** `sigma_pontos`, `sigma_medicoes`, `sigma_parametros`
- **Schemas Zod canônicos:** `zPontoCriar`, `zMedicaoRegistrar` em `*-comuns`

## Processamento Assíncrono e Filas (BullMQ)
- **Fila `calcular_agenda`:** Recalcula status e prazos de monitoramento.

## Rotas e Integração de IA
- **Rota `/llm.md`:** Disponibiliza catálogo dinâmico de endpoints e contratos.

---

PASSO 4 — Conectar com Código e UI

1. Verificar se mensagens e labels na UI seguem o vocabulário definido (rule mensagens-usuario).
2. Verificar se componentes e modais Vue possuem modalX.ajuda.md co-localizado (skill adicionar-ajuda).
3. Garantir que funções centrais e serviços possuem comentários claros de aplicação (rule jsdoc-padrao).
4. Assegurar que regras com 3+ critérios possuam .regras-negocio.md co-localizado (rule regras-negocio-md).

---

Checklist Final

• Documentação de usuário criada/atualizada em <modulo-wiki>/<modulo>/?

• Documentação técnica criada/atualizada em <modulo-wiki>/dev/<modulo>/?

• Glossário com os termos centrais do domínio documentado?

• Regras e entidades técnicas alinhadas com os schemas Zod do *-comuns?

• Rota /llm.md no backend reflete o módulo?

---

Referências

• Rule: rules/ddd-documentacao-primeiro.md
• Rule: rules/jsdoc-padrao.md
• Rule: rules/regras-negocio-md.md
• Skill: skills/adicionar-ajuda/SKILL.md