incremento-ssd

name	incremento-ssd
description	Orquestra o ciclo completo de um incremento no modelo SSD — situar, planejar, construir, verificar, revisar, consolidar. Use no início de qualquer incremento não-trivial; é a skill que conduz o agente principal pelos 6 passos do capítulo 24 do Manual.

Procedimento — 6 passos sem atalho

1. Situar

• Ler o CLAUDE.md (sempre carregado).
• Identificar o domínio afetado em docs/catalogo-dominios.md.
• Identificar o eixo da fase 25.2 ao qual o incremento serve (docs/catalogo-dominios.md seção "Mapeamento").
• Acionar o subagente explorador-dominio para mapear o estado atual: tabelas existentes, endpoints irmãos, políticas RLS, eventos publicados.
• Aguardar a resposta concisa antes de planejar.

Saída esperada: parágrafo curto descrevendo onde o incremento se encaixa.

2. Planejar

• Acionar o subagente Plan (nativo do Claude Code) em modo somente-leitura.
• Pedir um plano com:
  • arquivos que serão criados / modificados
  • abordagem técnica
  • skills a serem aplicadas
  • testes que acompanharão
  • impacto em outros módulos
• Apresentar o plano ao operador humano para aprovação. Sem aprovação, não avança.

Saída esperada: plano aprovado por escrito.

3. Construir

• Aplicar a skill apropriada ao tipo de incremento:
  • novo domínio → novo-dominio
  • nova tabela → nova-tabela
  • migração de schema → nova-migracao
  • novo endpoint → novo-endpoint
  • política RLS → politica-rls
• Escrever os testes junto com o código (não depois).
• Atualizar OpenAPI antes do código do endpoint.
• Tocar apenas os arquivos autorizados pela "fronteira de escopo" do prompt (capítulo 30).

4. Verificar

• Rodar a pirâmide de testes localmente (npm test, pytest, etc.).
• Para endpoints: verificar via conector postgres-hml que o estado do banco após chamada é o esperado.
• Para mudanças de RLS: teste explícito de isolamento entre microrregiões.
• Para fluxo de UI: subir o app, exercitar a jornada manualmente ou via Playwright.

Bloqueador: se algum teste falha, não prossegue para revisão. Volta ao passo 3.

5. Revisar

• Acionar revisor-seguranca (read-only) — obrigatório se o incremento toca endpoint, política, schema ou autenticação.
• Acionar revisor-lgpd (read-only) — obrigatório se o incremento coleta, mostra, exporta ou elimina dado pessoal.
• Aguardar achados.
• Endereçar todos os achados de severidade critica e alta. media e baixa podem virar tarefas separadas — registrar.
• Após resolução, operador humano lê o diff. Aprovação humana é indelegável.

6. Consolidar

• Atualizar docs/ se a estrutura mudou (catálogo de domínios, mapa do monorepo).
• Atualizar CLAUDE.md só se uma regra inegociável surgiu — caso contrário, mantém enxuto.
• Registrar ADR em docs/decisoes-arquitetura/ se uma decisão estrutural foi tomada.
• Resumir lições aprendidas em comentário no PR (vão pra retrospectiva da fase).
• Fechar o ciclo: o próximo incremento já nasce conhecendo este.

Regras de ouro

• Nenhum incremento começa sem contexto suficiente (passo 1).
• Nenhum incremento termina sem consolidar o contexto que produziu (passo 6).
• Um incremento, um prompt. Se o incremento precisa de "e", são dois.
• Plano antes de código. Plano ruim aprovado é incremento ruim construído.
• Autor nunca é revisor. O revisor-seguranca é sempre subagente distinto, read-only.

Quando descarrilhar, reiniciar

Se o passo 3 produz algo fora do esperado, não corrija linha a linha — reinicie o incremento dando ao passo 1 ou 2 o contexto que faltou. Refazer um incremento pequeno custa pouco; remendar um mal-fundamentado custa mais.

Saída

Incremento completo, em PR de draft, com:

• código + testes verdes
• OpenAPI atualizada (se aplicável)
• migração versionada (se aplicável)
• aprovação dos revisores
• diff revisado por humano
• ADR / notas consolidadas
• checklist de prontidão (docs/checklist-prontidao.md) com itens aplicáveis assinalados