NNNN — ¶

Status: RASCUNHO → DIAGNOSTICADO → EM CORREÇÃO → CORRIGIDO

O fix atravessa dois portões, cada um revisado por um subagente de contexto limpo, em até 3 rodadas. Máquina do plugin superpowers, régua em .claude/rubrics/. Qualquer Critical reprova; Important em aberto reprova salvo decisão registrada do usuário.

1. O diagnóstico (seções 1 a 4) é revisado na seção 5 (reprodução × causa raiz). É o portão barato: sem ele, o segundo mede o conserto contra um palpite.
2. A correção (o diff e os testes) é revisada na seção 11 (correção × regressão), com duas perguntas — atacou a causa ou o sintoma, e o que prova que não volta.

1. Sintoma¶

O que o usuário observa, do ponto de vista de quem usa o sistema. Tela, endpoint, papel envolvido, mensagem de erro exata. Anexe o que dá para citar (log, código de status, print).

2. Reprodução¶

Passos mínimos e determinísticos para o bug aparecer. Se não reproduz de forma confiável, diga isso e descreva quando aparece.

1. …

2. …

3. Ambiente: local / dev-remote / produção

4. Superfície: desktop / mobile / ambos — e breakpoint específico, se houver; se é agravado pelo PWA (tela instalada, bundle cacheado, offline)
5. Dados/pré-condições: papel, tenant, seed, estado necessário

3. Esperado × Atual¶

• Esperado: o que deveria acontecer.
• Atual: o que acontece.

4. Causa raiz¶

É a seção que o portão da seção 5 mede com mais rigor. Três coisas, e nenhuma substitui as outras:

• Onde — arquivo:linha, conferível. Nomear um módulo inteiro não localiza nada. Se for regressão, qual mudança introduziu (commit/spec/fix).
• O mecanismo — por que esta causa produz este sintoma, a cadeia do defeito até o que o usuário vê. É o que separa diagnóstico de palpite bem redigido.
• O alcance — onde mais a mesma causa morde. Helper compartilhado, token, guard, ordem de middleware: liste os outros pontos que passam por ali, ou diga que procurou e não há.

Não pule esta seção para "só corrigir". Correção sem causa raiz costuma tratar sintoma e o bug volta por outro caminho. "Ainda não sei" é resposta honesta no RASCUNHO — diga então o que já descartou; o que não vale é hipótese escrita como conclusão.

5. Revisão do diagnóstico¶

Preenchido pela revisão do diagnóstico (Superpowers systematic-debugging), rubrica .claude/rubrics/diagnostico.md. Registrar todas as rodadas, inclusive as reprovadas.

Resultado: aprovado na rodada N.

Pendências aceitas: o que a revisão ainda apontou e se decidiu não resolver, com o porquê. Vazio se não houver.

6. Correção¶

Onde vai mexer, por camada. Um bug pode viver em um app só — seja explícito.

apps/api¶

• Onde: model / schema / repository / service / router / migration
• O quê: …

apps/web¶

• Onde: página / componente / provider
• O quê: …
• data-testid: novos atributos, se a correção exigir (sustenta o e2e)
• Responsividade & PWA: a correção vale para desktop e mobile; se toca asset/estilo/layout, considerar o cache do service worker (PWA) na hora de validar

apps/e2e¶

• Teste de regressão: o cenário que falha hoje e passa depois da correção

Se algum app não é afetado, escreva "sem impacto" explicitamente.

7. Risco / impacto colateral¶

O que mais essa mudança pode afetar. Regra de negócio adjacente, migração de dados, outro fluxo que depende do mesmo código. Se toca dinheiro (pricing, billing, sinistro), diga como validou que não quebrou o cálculo.

8. Critérios de aceite¶

Verificável por quem não escreveu a correção. O primeiro deve ser sempre "o bug não reproduz mais".

• [ ] CA1. Seguindo os passos da seção 2, o comportamento agora é o esperado.
• [ ] CA2. …

9. Plano¶

• [ ] Escrever o teste que reproduz o bug e vê-lo falhar (apps/api/tests/ e/ou apps/e2e/) — antes de qualquer correção
• [ ] Corrigir a causa raiz — na ordem api → web → e2e se atravessar camadas
• [ ] Red-green verificado: teste passa → reverter a correção → rodar → falha → restaurar → passa. Se o fix é só visual, a prova é o script de screenshot nos dois viewports, com o que se conferiu
• [ ] make test e make lint sem apontamento novo nos arquivos tocados
• [ ] Se mexeu no web, validar no browser de verdade em desktop e mobile (e, se for build/PWA, reabrir a tela instalada para furar o cache)

10. Decisões em aberto¶

Perguntas que travam a correção, com quem decide. Esvaziar antes de DIAGNOSTICADO.

• [ ] …

11. Revisão da correção¶

Preenchido pela revisão da correção (Superpowers requesting-code-review), rubrica .claude/rubrics/correcao.md. Registrar todas as rodadas.

O teste sobreviveria à reversão? A evidência do red-green do Passo 5 — o comando rodado e a saída, não a impressão. "Revertida a correção, test_x falha em assert ...; restaurada, passa."

Defeitos aceitos: o que a revisão apontou e se decidiu não corrigir neste fix, com quem decidiu e por quê. Vazio se não houver.

12. Registro¶

Anotações durante a correção: o que era, o que virou, o que divergiu do plano. Preencher ao corrigir.