.agent/global/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 (../../wiki/<modulo>/) e de desenvolvimento (../../wiki/dev/<modulo>/).

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 ../../wiki é uma aplicação VitePress, onde a base factual do domínio é estruturada em dois níveis de acesso:

1. Wiki do Usuário (../../wiki/<modulo>/): Aplicação VitePress com acesso dos usuários e clientes (linguagem funcional, conceitos, glossário, fluxos e manuais operacionais).
2. Wiki de Desenvolvimento (../../wiki/dev/<modulo>/): 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 o Domínio do Módulo

Determinar qual área da ciência/gestão o módulo aborda:

Exemplo de módulo	Domínio	Destino Usuário	Destino Dev
SIGMA	Monitoramento ambiental (efluentes, piezometria, bombeamento)	../../wiki/e-licencie.sigma/	../../wiki/dev/e-licencie.sigma/
Licenciamento	Gestão de licenças (LP, LI, LO, condicionantes)	../../wiki/e-licencie/	../../wiki/dev/e-licencie/
Resíduos	Gestão de resíduos sólidos (PGRS, MTR, MTR-e)	../../wiki/e-licencie.residuos/	../../wiki/dev/e-licencie.residuos/
Qualificação	Qualificação e conformidade de fornecedores	../../wiki/e-licencie.qualifica/	../../wiki/dev/e-licencie.qualifica/

---

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

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 (../../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 ../../wiki/<modulo>/?
• Documentação técnica criada/atualizada em ../../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