invariant-guard — Codificação com Foco na Correção

O modelo sabe o que é um invariante de loop. Sabe que recursão precisa de um caso base. Sabe sobre listas vazias, estouro de inteiros e a diferença entre < e ≤. Ele apenas não anota isso antes de produzir o código, então entrega bugs sutis de correção que os testes não pegam.

invariant-guard corrige o comportamento. Declare os invariantes. Declare o caso base. Declare o argumento de terminação. Declare os casos extremos. Em seguida, escreva o código — e verifique se o código mantém o que você declarou.

Violar a letra destas regras é violar o espírito da habilidade. "Eu conheço este algoritmo" é a exata racionalização que entrega bugs de "off-by-one" (um a mais ou um a menos) e de pós-condição ausente.

Quando Usar Esta Habilidade

Use invariant-guard ao escrever ou revisar algoritmos onde a implementação óbvia está sutilmente errada:

• Pós-condição mais forte que o invariante natural do loop: maioria de Boyer–Moore, detecção de ciclo de Floyd, busca binária à esquerda vs. qualquer busca, partição QuickSelect.
• Mutação in-place com ponteiros de leitura+escrita: dedup-in-place, partição, rotação.
• Recursão com múltiplos parâmetros ou estado acumulador.
• Suspeitas de "off-by-one" com duplicatas, entradas vazias, valores de limite.
• Refinamentos iterativos que devem terminar: ponto fixo, Newton, EM.
• Qualquer função onde você se pega pensando "Eu conheço este algoritmo" — a armadilha geralmente está no contrato, não no corpo do loop.

Combina com lemmaly (escolhe o algoritmo) e mathguard (escolhe a matemática). Carregue invariant-guard depois que o algoritmo foi escolhido e antes que o corpo do loop seja escrito.

A Lei de Ferro

NO LOOP OR RECURSION WITHOUT A WRITTEN INVARIANT AND TERMINATION ARGUMENT

Se você não consegue escrever o invariante em uma frase, você não projetou o loop. Escreva código de qualquer maneira e você está codificando por palpite — e o bug estará no caso que você não enumerou.

Regras Inegociáveis

1. Todo loop recebe um invariante de uma linha. Antes de escrever qualquer loop, declare em uma frase o que é verdadeiro no topo de cada iteração. Exemplos:

   • "No topo do loop: result contém a soma de a[0..i)."
   • "No topo do loop: lo ≤ target_position ≤ hi."
   • "No topo do loop: seen contém todos os elementos processados até agora; dups contém todos os elementos que apareceram pelo menos duas vezes."

   Se você não consegue escrever o invariante em uma frase, você ainda não projetou o loop.

2. Todo loop recebe um argumento de terminação de uma linha. Nomeie a quantidade que estritamente diminui (ou estritamente aumenta em direção a um limite) a cada iteração. Exemplos:

   • "hi − lo estritamente diminui a cada iteração."
   • "i aumenta em 1 e é limitado superiormente por n."
   • "stack.length estritamente diminui a cada pop; nada é empurrado dentro deste ramo."

   Sem argumento de terminação, sem loop.

3. Toda recursão recebe um caso base explícito e uma medida. Antes de escrever uma função recursiva, declare:

   • O(s) caso(s) base — as menores entradas que retornam sem recursão.
   • A medida — um inteiro não negativo que estritamente diminui a cada chamada recursiva (por exemplo, len(xs), hi − lo, depth, n).
   • A combinação — como os resultados recursivos se combinam na resposta.

   Sem caso base + medida, sem recursão. (Recursão mútua: declare a medida através do ciclo.)

4. Liste os casos extremos antes de escrever, não depois. Para cada função que opera em uma coleção ou número, liste quais destes se aplicam e como eles se comportam:

   • Entrada vazia ([], "", null, undefined, None).
   • Singleton ([x]).
   • Elementos todos iguais.
   • Entrada já ordenada / ordenada reversamente.
   • Duplicatas (quando a unicidade é assumida).
   • Números negativos, zero, exatamente o valor de limite.
   • Estouro / subfluxo de inteiros no máximo/mínimo do tipo.
   • NaN, ±Infinito, -0, denormais (para floats).
   • Limites de "off-by-one": índice 0, índice n−1, índice n, comprimento 0, comprimento 1.
   • Modificação concorrente durante a iteração.

   Os casos que se aplicam devem ter cada um um comportamento esperado de uma frase escrito.

5. Torne estados ilegais inalcançáveis, não apenas não tratados. Prefira codificar restrições em tipos e estrutura para que o estado errado não possa ser construído:

   • Tipo soma sobre um monte de flags booleanas (Loading | Loaded(data) | Error(msg) em vez de {loading, data, error}).
   • Newtype para IDs que não devem ser trocados (UserId vs OrderId).
   • Tipo de lista não vazia quando a função requer pelo menos um elemento.

…