# Quality Revisao Aderencia

> OBRIGATORIO carregar antes de qualquer frase de conclusao em tarefa de implementacao, refatoracao, fix ou extensao. Frases-gatilho que EXIGEM checklist rodada antes: "concluido", "completo", "feito", "pronto", "terminei", "finalizado", "the refactoring is complete", "tudo certo", "refatoracao concluida", "feature pronta", ou qualquer declaracao de fim de tarefa. Sem essa checklist rodada e report…

- **Type:** Skill
- **Install:** `agentstack add skill-gianverdum-ai-dev-skillset-quality-revisao-aderencia`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [gianverdum](https://agentstack.voostack.com/s/gianverdum)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [gianverdum](https://github.com/gianverdum)
- **Source:** https://github.com/gianverdum/ai-dev-skillset/tree/main/.agents/skills/quality-revisao-aderencia

## Install

```sh
agentstack add skill-gianverdum-ai-dev-skillset-quality-revisao-aderencia
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Revisao de Aderencia a Skills e Rules

Use esta skill como ultima etapa antes de declarar uma tarefa concluida e, em mudancas grandes, tambem ao terminar cada etapa significativa (modulo novo, camada nova, refator estrutural). O objetivo e fechar o ciclo TDD/quality e impedir desvios silenciosos.

## Quando rodar

**Regra absoluta de gatilho — antes de qualquer frase de conclusao:**

Antes de escrever no resumo final QUALQUER uma destas frases (ou equivalente em outro idioma), VOCE PRECISA ter rodado a checklist objetiva desta skill:

- "concluido" / "completo" / "completa" / "pronto" / "feito" / "terminei" / "finalizado" / "encerrado"
- "the refactoring is complete" / "refactor is done" / "implementation complete" / "all done"
- "refatoracao concluida" / "feature pronta" / "task pronta" / "tudo certo"
- Qualquer declaracao categorica de fim de tarefa (mesmo implicita: "rodei tudo, passou", "all checks pass", etc.)

Se a checklist objetiva (secao "Pontos a verificar") tem **2 ou mais itens vermelhos**, voce esta PROIBIDO de usar qualquer dessas frases. Use o formato WIP transparente em vez (secao "Formato no reporte final QUANDO refatoracao esta em WIP").

Declarar conclusao com itens vermelhos sem WIP = DESVIO grave de honestidade, anula o credito do trabalho feito.

**Outros gatilhos:**

- Ao terminar uma implementacao, fix ou refator, antes do resumo final ao usuario.
- Ao concluir um modulo novo, antes de seguir para o proximo.
- Ao concluir uma camada (domain/application/interface) novamente, antes de seguir.
- **Sempre que uma extensao criar modulo novo**: aplique a checklist completa SEPARADAMENTE ao modulo novo (suite e2e propria, README proprio, cobertura propria, literal unions, etc.), mesmo que o modulo existente ja tenha cobertura completa.
- Quando o usuario pedir explicitamente revisao de aderencia.

**Sintoma da skill nao rodada (auto-deteccao):**

Se voce esta prestes a escrever uma frase de conclusao e NAO consegue listar mentalmente o status (❌/✅) dos 9 itens da checklist objetiva nem dos anti-padroes desta secao, voce nao rodou a skill. Pare, leia esta skill, rode item-a-item, depois decida entre "concluido" ou "WIP transparente".

## Fluxo

1. Liste as skills e rules ATIVAS para a stack e tipo de mudanca (consulte `.agents/skills` e `.agents/rules`).
2. Identifique se a mudanca e **criacao inicial** ou **extensao** (projeto existente). Em extensao, identifique modulos NOVOS criados na mudanca vs modulos EXISTENTES tocados.
3. Enumere os pontos verificaveis: estrutura, camadas, nomes, tipagem do dominio, idioma do codigo, codigos de erro, lint, testes, cobertura, documentacao.
4. **Em extensao, aplique a checklist completa SEPARADAMENTE para cada modulo novo.** Modulo novo herda zero credito do modulo existente: precisa ter sua propria suite e2e completa (4 cenarios minimos quando aplicavel), seu proprio README, sua propria cobertura ≥ 80%, suas proprias literal unions, etc.
5. Para cada ponto, compare com o codigo produzido (working tree e diff). Marque cada item como **OK** ou **DESVIO**.
6. Quando houver desvio, decida:
   - Corrigir agora (default) se o ajuste cabe no escopo da tarefa.
   - Registrar bloqueio concreto se a correcao depende de algo externo.
7. Aplique as correcoes, rode lint/format/tests novamente e reavalie ate ficar limpo.
8. **Em extensao, reporte tambem debito herdado visivel** na area tocada (DESVIOs pre-existentes nao introduzidos por esta mudanca, mas visiveis no modulo/arquivo editado). Veja secao "Debito herdado".
9. Reporte ao usuario o resultado do checklist com OK/DESVIO/corrigido por item, antes do resumo final da tarefa.

## Pontos a verificar

Esta lista cobre os desvios mais comuns observados em iteracoes anteriores. Ela nao substitui as skills/rules; e um checklist operacional.

### Arquitetura

- Identifique a skill de arquitetura ativa antes de avaliar: Clean Arch (`architecture-ddd-clean-arch`) exige `domain`/`application`/`interface`; Hexagonal (`architecture-ddd-hexagonal`) exige `domain`/`application`/`adapters/in`+`adapters/out`. A escolha segue a precedencia: padrao do projeto > pedido do usuario > default Clean Arch. Modulo misturando os dois layouts e DESVIO.
- Modulo tem as camadas minimas exigidas pela arquitetura ativa.
- Camada de entrada (interface ou `adapters/in`) chama application/caso de uso; application chama domain. Sem atalhos da interface direto para o domain.
- Dominio NAO contem: parsing textual, IO, serializacao, framework, mensagens humanas, import de adapter.
- Application NAO faz parsing textual cru (tokenizar string, split, regex em argv, `Number(text)`, `JSON.parse(body)`). Esses passos sao da camada de entrada (interface ou `adapters/in`). Application recebe DTO/Request ja tipado e orquestra dominio.
- Em Hexagonal: portas de saida declaradas no nucleo; implementacoes em `adapters/out`; wiring em `config/` ou entrypoint.

### Tipagem do dominio

- Quando o conjunto de valores aceitos for finito (operador, status, papel, codigo), a assinatura do dominio expressa isso por tipo (`Literal`, *literal union*, `enum`, `typed alias`).
- O tipo expressivo esta USADO na assinatura, nao apenas exportado.
- Nao ha validacao duplicada do conjunto (uma vez na interface, outra dentro do dominio com `default`/`else`).

### Modelagem tatica (Aggregate, Entity, Value Object)

- Conceitos com identidade ou semantica propria (`TaskId`, `UserId`, `TenantId`, `Money`, `BillingMonth`, `EmailAddress`, `Cpf`) estao modelados como **Value Object** com invariantes no construtor, nao como `string`/`number` cru.
- Aggregates expoem um **Aggregate Root** explicito como **classe com metodos**, nao type/record mutavel por funcoes externas. Entities filhas do aggregate sao mutaveis SO via metodos do root (ex.: `project.completeTask(...)`, nunca `task.status = "done"` direto nem `setProjectTaskStatus(project, ...)` externa que muta o campo).
- **Aggregate root e dono da colecao** de seus filhos. Composite externo (`type X = XAggregate & { children: ... }` definido em outro modulo ou no shared-kernel, com mutacao da colecao por fora via cast) e DESVIO; a colecao mora dentro do aggregate root, manipulada por seus metodos.
- Referencias entre aggregates sao por **ID** (VO de identidade), nao por objeto direto.
- Cross-BC: nenhum BC importa entity ou aggregate de outro BC. Comunicacao via porta + DTO proprio do BC consumidor, com VOs de identidade compartilhados em `src/shared-kernel/value-objects/` ou duplicados intencionalmente.

### Shared-kernel restrito

`src/shared-kernel/` so pode conter: `value-objects/` (VOs de identidade compartilhados) + `errors.ts` opcional (classe base de erro) + `event-types.ts` opcional (tipos de evento). Tudo o mais e DESVIO:

- `shared-kernel/application/` = DESVIO.
- `shared-kernel/infrastructure/` = DESVIO.
- `shared-kernel/interface/` = DESVIO.
- `shared-kernel/domain/.ts` com state composto cross-BC (`ProjectManagementState`, `Tenant & { clients }`) = DESVIO.
- Helpers como `findTenant`/`findClient`/`findProject` em `shared-kernel/application/` = DESVIO.

Quando shared-kernel cresce alem disso, o monolito foi renomeado, nao quebrado.

### Isolamento de estado por BC

Cada BC tem state, repositorio e schema persistido proprios:

- Port de repositorio do BC retorna `State` proprio (ex.: `TenantState`), NAO um composto cross-BC (`ProjectManagementState`).
- Adapter concreto implementa o repositorio diretamente, NAO via classe vazia herdando do shared-kernel.
- Schema persistido por BC. Se a stack obriga arquivo unico, sub-arvore versionada por BC com cada repositorio acessando SOMENTE a sua sub-arvore.

### Layout estrutural

- Cada modulo segue `src//{domain, aggregates, value-objects, application, infrastructure, interface}`.
- `aggregates/` e `value-objects/` ficam **no mesmo nivel de `domain/`**, NUNCA dentro de `domain/`.
- Cada aggregate root em arquivo proprio (`aggregates/.ts`). Cada VO em arquivo proprio (`value-objects/.ts`).
- `src/shared-kernel/value-objects/` na RAIZ de `src/` para VOs de identidade compartilhados. Nunca dentro de outro modulo.
- Bounded context separado = `src//` irmao, com estrutura completa. Subpastas dentro de `domain/` (`domain/tenancy/`, `domain/billing/`) NAO sao BCs.

### Idioma do codigo

- Identificadores em ingles (variaveis, funcoes, classes, modulos, pacotes, testes).
- Mensagens ao usuario nao sao literais traduzidos no dominio/application. Dominio/application lancam codigo estavel snake_case ingles; interface resolve para texto via dicionario/i18n.

### Nomes e estrutura

- Nome do pacote/modulo reflete o DOMINIO, nao a interface. Sufixos `_cli`, `_api`, `_web` so no nome publicado.
- `src/` na raiz; sem pasta intermediaria com nome do projeto.
- Testes seguem a rule da linguagem: colocalizados (Go/Rust/TS/JS) ou em `tests//` (Python/PHP/etc).
- README na raiz e README de cada modulo (sem README de submodulo de camada).

### Lint, format, manifesto

- Linter idiomatico instalado e configurado (ruff, biome/eslint, clippy, golangci-lint, etc.).
- Scripts `lint` e `format` no manifesto invocam ferramentas REAIS, nao alias de `typecheck`/`build`/`test`.
- Runtime declarado em projeto novo (`engines.node`+`.nvmrc` em Node, `requires-python` em Python, etc.).
- Lint roda limpo, ou apontamentos foram corrigidos. Nenhum aviso silenciado sem justificativa.

### Testes e cobertura

- Suite roda verde.
- Cobertura >= 80% ou bloqueio explicado.
- Testes cobrem caminho feliz e erros relevantes; nao ha teste vazio ou snapshot sem asseracao.
- Se o modulo persiste estado externo (arquivo, banco, fila, cache, broker, HTTP) ou expoe entrypoint executavel (CLI, HTTP server, daemon), existe ao menos um teste e2e cobrindo o fluxo cross-command/cross-request, alem de unit e integration. Integration sozinho NAO basta.
- Se o modulo tem autorizacao/permissao, validacao cruzada ou multiplos comandos, a suite e2e cobre tambem fluxos criticos de erro (permissao negada, recurso inexistente, validacao de entrada), nao apenas o happy path.
- **Em extensao**: modulo novo criado durante a extensao precisa de suite e2e propria com cobertura completa dos 4 cenarios (happy + permission_denied + not_found + invalid_input), independente do modulo existente ja ter cobertura completa. O fato de o modulo existente ter 6 e2e no padrao nao isenta o modulo novo de cobrir os mesmos cenarios para suas proprias operacoes.

### Portas, casos de uso e politicas

- Quando ha 2+ portas (interfaces de saida) na `application`, cada uma vive em seu proprio arquivo em `application/ports/.ts` (Clean Arch ou Hex). Multiplas portas declaradas dentro de `use-cases.ts` = DESVIO.
- Quando ha 5+ casos de uso na `application`, cada um vive em seu proprio arquivo em `application/use-cases/.ts`. Arquivo unico `use-cases.ts` ou `Service` monolitico com 5+ metodos publicos = DESVIO.
- Quando o dominio expoe 3+ funcoes `assertCan*`/`canDo*`/`mayAccess*` que so diferem em listas de papeis/estados aceitos, substitua por uma policy table (`Record>`) + helper generico `assertCan(role, action)`. Funcoes espelhadas = DESVIO.
- Funcao `assertCan*`/`assert*`/`validate*` com corpo vazio ou apenas `return;` mantida por simetria = DESVIO; remova ou absorva no helper generico.

### Codigos de erro

- O `code`/`kind`/`reason` da classe de erro deve ser **enumeracao explicita** (literal union em TS, `Literal[...]`/`Enum` em Python, `enum` em Rust/Java/C#). `code: string` cru = DESVIO; perde a garantia de exaustividade entre codigos e catalogo de mensagens.
- O dicionario de mensagens da interface deve ser tipado como `Record` (ou equivalente). `Record` = DESVIO; aceita typo silenciosamente e nao alerta sobre codigo novo sem mensagem.

### Fronteira de modulo

- Cada diretorio irmao em `src/` e um bounded context com vocabulario proprio. Adapter de persistencia, cliente HTTP, parser, mapper do PROPRIO modulo nao sao modulos irmaos: ficam como submodulo de camada (`infrastructure/` em Clean Arch ou `adapters/out/` em Hexagonal) dentro do modulo dono.
- A decisao vale tambem em extensoes. Em projeto existente, bounded context novo (vocabulario proprio, ciclo de vida proprio) vira `src//` irmao, NUNCA enxertado no modulo existente. "Preservar padrao local" vale para naming/estilo/layout, nao para misturar bounded contexts no mesmo modulo.
- Sintomas de vazamento (cada um sozinho ja e DESVIO): tipo de entidade existente ganhou campo com vocabulario do novo dominio (`Task.completedBillingMonth`, `User.subscriptionTier`); `State`/agregado existente ganhou colecao do novo dominio (`ProjectManagementState.monthlyCharges`); constante/regra do novo dominio em arquivos do dominio existente (`COMPLETED_TASK_CHARGE_CENTS` em `domain/project.ts`); policy table existente ganhou actions do novo dominio (`issue_monthly_charges`); UX existente passou a exigir campos do novo dominio (`complete-task --billing-month`); README do modulo existente cita novos dominios no titulo/responsabilidade.

### Documentacao

- README da raiz e do modulo refletem a estrutura atual.
- Comandos documentados foram validados.

## Debito herdado (em extensao)

Em extensao de projeto existente, o agente toca arquivos/modulos que podem conter DESVIOs **pre-existentes** — codigo nao introduzido por esta mudanca mas visivel no diff ou na vizinhanca. A regra:

- **Reportar, nao obrigar correcao.** Debito herdado vai em secao separada na resposta final, listada como "Debito herdado visivel" (nao como "DESVIO desta mudanca"). A decisao de corrigir e do usuario.
- **Nao expandir escopo silenciosamente.** Refatorar codigo legado fora do pedido do usuario contraria a precedencia "preservar padrao local + escopo da tarefa". Mencionar o debito permite ao usuario decidir conscientemente.
- **Quando corrigir junto:** apenas se (a) a correcao e trivial e diretamente relacionada ao escopo, OU (b) o debito impede a entrega correta da mudanca, OU (c) o usuario autorizou a refatoracao. Caso contrario, apenas reporte.

Exemplos de debito herdado a reportar:

- `*Service` monolitico com 5+ metodos publicos (regra de "use cases por arquivo" violada antes da mudanca).
- Funcao `assertCan*` vazia ou funcoes espelhadas que sobreviveram a iteracoes anteriores.
- `code: string` cru em classe de erro existente.
- `Record` em catalogo de mensagens antigo.
- Tipos sem `readonly` quando o padrao do projeto e imutavel.
- `any` remanescente em codigo legado.
- README desatualizado para a estrutura atual.

### Formato no reporte final

```
## Revisao de aderencia

### DESVIOs desta mudanca (corrigidos)
- ... (lista de itens corrigidos)

### Debito herdado visivel (nao corrigido nesta mudanca)
- src/project-management/application/project-management-service.ts: classe com 11 metodos publicos viola a regra "5+ casos de uso em arquivos proprios". Pre-existente; correcao fora do escopo desta extensao.
- ...
```

### Formato no reporte final QUANDO refatoracao esta em WIP

Quando a checklist objetiva de conclusao (`process-refatoracao-segura` secao 7) tem 2+ itens falhando, NUNCA declare "refatoracao concluida". Use este formato:

```
## Refatoracao em andamento (WIP)

### Feito
- (lista do que foi efetivamente movido/extraido/migrado)

### Pendente (bloqueia "concluido")
- (lista objetiva: o que ainda precisa ser feito para fechar a checklist objetiva)
- (cite os itens da checklist que ainda falham, com caminho dos arquivos envolvidos)

### Itens da checklist objetiva (status atual)
1. Modulo original reduzido para ~30% ou removido: ❌/✅
2. Cada BC novo com estrutura completa: ❌/✅
3. Composition root roteando BCs novos: ❌/✅
4. Suite de testes por BC novo: ❌/✅
5. Migracao de dados decidida e implementada: ❌/✅
6. Isolamento de estado real (cada BC com state/port/repo/schema proprios; sem repositorio vazio herdando): ❌/✅
7. shared-kernel dentro do limite (so value-objects + opcionalmente errors/event-types): ❌/✅
8. Nenhum modulo (independente do nome) define composite cross-BC ou e "monolito disfarcado" (sem aggregates/use-

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [gianverdum](https://github.com/gianverdum)
- **Source:** [gianverdum/ai-dev-skillset](https://github.com/gianverdum/ai-dev-skillset)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-gianverdum-ai-dev-skillset-quality-revisao-aderencia
- Seller: https://agentstack.voostack.com/s/gianverdum
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.