---
name: documentar-dominio-modulo
scope: global
updatedAt: "2026-09-01"
description: >
  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 `<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 (`<base_projeto>/../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 (`<base_projeto>/../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

Os destinos canônicos da documentação na aplicação VitePress (`<base_projeto>/../wiki`) são:
- **Wiki do Usuário:** `<base_projeto>/../wiki/<modulo-id>/`
- **Wiki de Desenvolvimento:** `<base_projeto>/../wiki/dev/<modulo-id>/`

---

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

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

```markdown
# [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 (`<base_projeto>/../wiki/dev/<modulo>/`)

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

```markdown
# [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 `<base_projeto>/../wiki/<modulo>/`?
- [ ] Documentação técnica criada/atualizada em `<base_projeto>/../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`