---
name: documentar-dominio-modulo
scope: global
updatedAt: "2026-10-14"
description: >
  Guia para documentar o domínio científico/técnico de cada módulo nas wikis
  de usuário (<modulo-wiki>/<modulo-id>/) e de desenvolvimento (<modulo-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 operacional ou ambiental (licenciamento, efluentes, bombeamento, resíduos, projetos, atendimento, etc.). O repositório `<modulo-wiki>` (configurado em `memorias-ia/modulo.yml`, com fallback padrão para `../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 canônico do módulo
- `modulo-caminho`: rota base na URL
- `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:

```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 entidades base.
2. Lançamento e acompanhamento de registros.
3. Emissão de relatórios e acompanhamento de conformidade.
```

### Inclusão de Imagens, Diagramas e Manuais em PDF
Para enriquecer a Wiki com capturas de tela ou manuais, envie os arquivos para o MinIO Paiol antes de incluí-los no Markdown:
```bash
./.agent/scripts/upload-paiol-wiki.sh <caminho-do-arquivo> <slug-funcionalidade>
```
Utilize exclusivamente a URL pública gerada (`https://paiol.idz.one/wiki/...`) no Markdown. **Nunca comite arquivos binários no Git da Wiki.**

---

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

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:** `<modulo>_entidade_a`, `<modulo>_entidade_b`, `<modulo>_parametros`
- **Schemas Zod canônicos:** `zEntidadeCriar`, `zRegistroAtualizar` em `<modulo>-comuns`

## Processamento Assíncrono e Filas (BullMQ)
- **Fila `processar_agenda`:** Recalcula status e prazos operacionais.

## 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 possuem `{componente}.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` na Wiki de Desenvolvimento (rule `regras-negocio-md`).

---

## Checklist Final

- [ ] Documentação de usuário criada/atualizada em `<modulo-wiki>/<modulo-id>/`?
- [ ] Documentação técnica criada/atualizada em `<modulo-wiki>/dev/<modulo-id>/`?
- [ ] Glossário com os termos centrais do domínio documentado?
- [ ] Regras e entidades técnicas alinhadas com os schemas Zod do `<modulo>-comuns`?
- [ ] Rota `/llm.md` no backend reflete o módulo?
- [ ] Imagens, manuais e anexos hospedados no MinIO Paiol (sem binários no Git da Wiki)?

---

## Referências

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