Freeze Spec — Auditoria e Contratos de Codigo Existente

PRIMEIRO PASSO (obrigatorio)

Ao carregar esta skill, SEMPRE exibir este header antes de qualquer outra acao:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🧊 FREEZE SPEC — Skill carregada
Modulo: <nome do modulo recebido>
Output: docs/superpowers/freeze/<slug>/
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Gera documentacao retroativa ("freeze specs") que funciona como contrato inviolavel do codigo que JA EXISTE. Diferente de design specs (features novas), freeze specs documentam o estado atual para prevenir regressoes.

Quando usar

• Antes de modificar um modulo complexo pela primeira vez
• Apos bugs causados por mudancas que quebraram funcionalidades adjacentes
• Para qualquer arquivo com mais de 500 linhas ou mais de 3 componentes
• Periodicamente para atualizar specs desatualizadas

Input esperado

O operador vai dizer uma dessas formas:

• /freeze PainelDeVendas
• /freeze src/pages/ProfessionalPortal.tsx
• /freeze agendamento (voce resolve para os arquivos corretos)
• /freeze (sem args = lista modulos sem freeze spec e sugere por onde comecar)

Workflow de Execucao

Passo 1: Resolver o modulo

Mapear o input para os arquivos reais:

• Se for nome de pagina: buscar em src/pages/
• Se for nome de feature: buscar arquivos relacionados (frontend + backend + service)
• Listar TODOS os arquivos que o modulo toca

Passo 2: Analisar o codigo

Para CADA arquivo do modulo:

1. Identificar componentes/funcoes — nome, linhas inicio-fim, props/params
2. Mapear dependencias — quais rotas API cada componente consome
3. Identificar isolamento — funcao de modulo vs componente aninhado vs inline
4. Detectar state compartilhado — quais variaveis sao acessiveis de onde
5. Mapear imports — componentes externos usados

Passo 3: Gerar a estrutura

Criar pasta docs/superpowers/freeze/<modulo-slug>/ com:

_INDEX.md (obrigatorio)

# <Nome do Modulo> — Freeze Spec Index

**Ultima auditoria**: YYYY-MM-DD
**Arquivos cobertos**: lista de arquivos
**Total componentes**: N

## Mapa de Componentes

| Componente | Arquivo | Linhas | Tipo | Depende de |
|------------|---------|--------|------|------------|
| ListaDeItens | PainelDeVendas.tsx | 1923-2145 | funcao modulo | CalTab (via props) |
| DetailSidebar | PainelDeVendas.tsx | 6318-7183 | funcao modulo | PainelDeVendas (via props) |

## Regras Globais do Modulo
1. Regra X
2. Regra Y

## Dependencias Entre Componentes
- CalTab → ListaDeItens (passa appts, onAppt)
- CalTab → WeekView (passa appts, onDay)
- PainelDeVendas → DetailSidebar (passa appt, profs, rooms)

<componente>.md (1 por componente)

# <Componente> — Freeze Spec

**Arquivo**: path/to/file.tsx
**Linhas**: NNNN-MMMM
**Tipo**: funcao de modulo | componente inline | hook | service
**Ultima auditoria**: YYYY-MM-DD

## Assinatura
function NomeComponente({ prop1, prop2 }: { prop1: Type; prop2: Type })

## O que faz
Descricao concisa em 2-3 linhas.

## Props/Params (contrato de entrada)
- prop1: Tipo — descricao
- prop2: Tipo — descricao

## State interno
- [stateName, setStateName] = useState(default) — para que serve

## Rotas API consumidas
- GET /admin/scheduling/calendar → { appointments, blocks }
- PUT /admin/scheduling/appointments/:id → atualiza appointment

## O que renderiza
- Lista concisa dos elementos visuais

## Regras (NAO QUEBRAR)
1. E funcao de MODULO — NAO tem acesso a state de outros componentes
2. Click no card chama onAppt(a) — NAO navegar diretamente
3. ...regras especificas...

## Historico de mudancas
- 2026-04-07: Corrigido mobile nav que estava dentro desta funcao por engano
- 2026-04-06: Adicionado detalhe do item badges nos cards

Passo 4: Validar

• Verificar que TODOS os componentes do arquivo estao cobertos
• Verificar que as linhas inicio-fim estao corretas
• Verificar que as rotas API existem no backend
• Contar componentes no INDEX = componentes com spec individual

Passo 4b: Conferir conflito com o CLAUDE.md (OBRIGATORIO)

Freeze spec descreve o codigo como ele E. O CLAUDE.md descreve como o codigo DEVE ser. Quando os dois discordam, a freeze spec vira armadilha ativa: o proximo agente le o contrato, obedece, e implementa exatamente o que a regra global proibe.

Para CADA regra escrita em "Regras (NAO QUEBRAR)" e em "Regras Globais do Modulo":

1. Procurar no CLAUDE.md (raiz do projeto e /opt/apps) se existe regra OBRIGATORIA sobre o mesmo assunto — recorte de query, envio de mensagem, rota publica, fuso, dado sensivel.
2. Se a regra da spec contradiz a regra global, NAO escrever a regra como esta no codigo. Escrever a regra CORRETA (a do CLAUDE.md) e marcar com um aviso o que o codigo ainda faz:

4. **Receita = caixa da CLINICA** ... usar `filtroOficialSql('po')`.
   **NUNCA escrever `status = 1` solto** — regra obrigatoria do CLAUDE.md.
   AVISO: o codigo ainda usa o literal (`relatorioService.js:83`) — correcao pendente na <frente>.

3. Reportar ao operador todo conflito encontrado, com o efeito medido no banco quando aplicavel.

Caso real (04/09/2026): a regra 4 de freeze/aquisicao/acquisition-service.md mandava status = 1, proibido pelo CLAUDE.md desde 25/08. Era texto de 06/2026 que ficou para tras quando o fechamento migrou para filtroOficialSql. Um agente que lesse so o contrato implementaria o literal proibido — e a spec ainda afirmava ser "a mesma fonte do /admin/financial/dashboard", afirmacao que tinha deixado de ser verdade.

Passo 5: Reportar

Mostrar ao operador:

• Quantos componentes foram mapeados
• Quais regras criticas foram identificadas
• Se ha componentes que deveriam ser extraidos para arquivos separados (sugestao)

Formato dos nomes de arquivo

• Pasta: docs/superpowers/freeze/<modulo-slug>/
• INDEX: _INDEX.md
• Componentes: <nome-kebab-case>.md (ex: detail-sidebar.md, day-view.md)

Atualizar spec existente

Se ja existe freeze spec para o modulo:

1. Ler a spec existente
2. Comparar com o codigo atual
3. Atualizar linhas, props, rotas que mudaram
4. Adicionar entrada no Historico de mudancas
5. NAO apagar regras existentes sem confirmar com operador

Sem argumentos (/freeze)

Se invocado sem argumentos:

1. Listar todos os arquivos em src/pages/ e server/ com mais de 500 linhas
2. Cruzar com freeze specs existentes em docs/superpowers/freeze/
3. Mostrar tabela: arquivo | linhas | tem freeze? | ultima auditoria
4. Sugerir os 3 modulos mais criticos para auditar primeiro