m1nga/iteration-close

iteration-close — destilar, descartar, comprovar retomada, ensaiar bootstrap, semear próximo

Um produto que itera para sempre acumula duas dívidas silenciosas, e este skill paga ambas em todo limite de iteração — com segurança (nada se perde) mas impiedosamente (nada morto é mantido):

• Arquivos mortos persistem e apodrecem em duas-verdades — uma árvore descontinuada fica por semanas; um runbook continua afirmando que um componente "não foi construído" muito depois de ter sido lançado.
• Conhecimento que vive apenas em uma janela de chat morre com ela — pipelines inteiros em funcionamento morreram em rascunhos; decisões difíceis morrem com a sessão. Mantenha a lição, não o artefato.

É genérico: funciona em qualquer repositório lendo as próprias convenções do repositório e, onde uma convenção está ausente, cria o mínimo em vez de assumir ou gerar erro. "Uma nova janela ou nova máquina pode continuar" é uma ESPERANÇA até ser TESTADO; estar atualizado (pull) é sempre seguro, mas publicar (push) é uma escolha deliberada. Responda no idioma em que o usuário está trabalhando.

Duas formas de executar

• Fechamento completo (padrão): todas as cinco fases, em ordem. Use quando uma iteração/slice estiver concluída e o usuário quiser encerrá-la de ponta a ponta.
• Apenas descarte (limpeza independente): quando o usuário pedir apenas para limpar arquivos antigos/mortos/substituídos, execute a Fase 2 sozinha — NÃO force o fechamento completo de cinco atos. As pré-condições ainda se aplicam: execute o Passo 0 (orientação), as verificações de recusa com falha fechada, e uma verificação pontual da Fase 1 com escopo no inventário de exclusão — qualquer item cuja lição ou decisão viva apenas no chat é destilado em um arquivo rastreado primeiro, ou permanece fora do inventário. Todas as regras da Fase 2 se aplicam inalteradas, incluindo a barreira de sim explícito e a regra de quarentena.

Passo 0 — orientar-se para ESTE repositório (descobrir, senão planejar criar)

Leia qualquer documento de entrada que exista — CLAUDE.md / AGENTS.md / README / um índice docs/ — e descubra seis coisas. Use o que encontrar; onde algo estiver ausente, anote como uma lacuna que este fechamento preencherá (cada fase abaixo explica como), nunca invente um caminho que não existe.

1. Registro de lição/decisão — onde este repositório guarda decisões? (CHANGELOG, docs/adr/, DECISIONS.md, ou um registro específico do repositório.) Se nenhum, a Fase 1 cria um único DECISIONS.md.
2. Comando de upload confirmado — uma etapa de push deliberada (bin/sync, make deploy, uma disciplina documentada de git push)? Se sim, ESSE é o canal de upload; nunca o ignore. Se nenhum, a Fase 3a usa git push simples após um diffstat + confirmação.
3. Comando de bootstrap — como um clone fresco ganha vida? (bin/bootstrap, bin/sync-setup, install.sh, make setup, uma instalação via gerenciador de pacotes.) Se nenhum, a Fase 4 cria um.
4. Comando de teste — da configuração de CI, scripts package.json, um Makefile, ou o padrão da linguagem (pytest / go test / cargo test / npm test). Se nenhum for detectável, o repositório ainda não tem suíte executável: trate isso como um estado explícito abaixo — nunca leia como "verde", nunca RECUSE em um repositório que legitimamente não tem nenhum.
5. Habilidade de fundamentação/barreira — uma habilidade de fundamentação de produto ou barreira de pré-construção? Se sim, sua lista de verificação "pós-construção" é sua barreira de pré-fechamento. (Barreiras específicas do produto vivem dentro do repositório do produto; este skill permanece genérico e as adia.)
6. Diretórios declarados de dados/recuperação/quarentena — diretórios que o documento de entrada nomeia como contendo dados reais, material de recuperação ou arquivos em quarentena. Estes estão isentos de toda regra "diretórios em forma de arquivo não devem existir" abaixo e nunca devem aparecer em um inventário de exclusão.

Recusar executar (falha fechada)

Não feche no meio da iteração — você perde pele E carne. RECUSE (em ambos os modos de execução) se: o diretório não for um repositório git (pare e diga isso — executar git init é decisão do usuário); a suíte de teste existir e estiver realmente FALHANDO (uma suíte ausente não é uma falha — veja Passo 0.4); uma barreira adversarial, se o repositório tiver uma, estiver pendente ou CHANGES-REQUIRED; ou outro agente/faixa tiver trabalho não commitado no meio do slice em caminhos que você tocaria. Diga o que está bloqueando e pare.

Em um fechamento completo, execute as fases EM ORDEM. Cada uma tem um teste de saída; nunca prossiga após um teste de saída falho.

Fase 1 — DESTILAR (barreira de salvamento: nada morre antes de sua lição ser registrada)

1. Varra as decisões nascidas no chat desta iteração para o registro de decisões do repositório (Passo 0.1), cada uma com seu status e fonte. Se o repositório ainda não registra decisões em lugar nenhum, criar o registro é parte desta fase — um único DECISIONS.md na raiz do repositório é suficiente. Uma decisão que existe apenas em uma janela de chat não existe; não deixe decisões destiladas sem um lar rastreado.
2. Novos invariantes/regras descobertos nesta iteração → o arquivo de contratos do repositório, ou na falta deste o registro de decisões — idealmente cada um como um teste. Se nenhum existir, crie o registro de decisões e coloque-os lá. Exclua o artefato, mantenha o invariante.
3. Verificação de capacidade apenas de sessão: esta iteração dependeu de algo que vive APENAS em um prompt, um rascunho ou na memória de alguém? Promova-o para o repositório (código / habilidade / documento) ou registre sua exclusão deliberada. Nomeie cada um explicitamente — é aqui que pipelines morrem.
4. Se a ESTRUTURA mudou, atualize — ou, se nenhuma existir e a estrutura agora for não trivial, crie — uma breve nota de arquitetura/sistema para que ela ainda descreva a realidade. Atualize qualquer quadro de status (por exemplo, um documento de progresso) se o repositório tiver um.

TESTE DE SAÍDA: grep pelas decisões e invariantes chave desta iteração dentro do repositório — cada um encontrável em um arquivo rastreado. Qualquer coisa encontrável apenas no chat = Fase 1 não concluída.

Fase 2 — DESCARTAR (exclusão impiedosa; o histórico do git é o ÚNICO arquivo)

1. Construa um inventário de exclusão com evidência, uma linha cada: caminho | por que morto | o que o substitui. Cubra módulos/especificações substituídos, diretórios mortos/vazios, resíduos de desenvolvimento (arquivos de rascunho, lixo estilo mktemp, linhas de teste em armazenamentos de formato real), documentos de plano/TODO concluídos e DOCUMENTOS DESATUALIZADOS — execute uma passagem de contradição docs-vs-código; um documento que afirma o que o código contradiz é pior do que nenhum. Marque cada linha como RASTREADA ou NÃO RASTREADA (git ls-files --error-unmatch <caminho>), porque as duas têm destinos diferentes (regras 3 e 4).
2. Apresente o inventário COMPLETO ao usuário e aguarde um sim explícito antes de excluir qualquer coisa. Aprovação parcial é aceitável — aja apenas nas linhas aprovadas. O agente nunca pressiona botões irreversíveis por conta própria; "o usuário pediu uma limpeza" autoriza construir a lista, não executá-la.
3. Arquivos rastreados: apenas git rm. NENHUM diretório _archive/, NENHUM .bak, NENHUM renomeio old-/legacy-, NENHUM cadáver comentado. Recuperação = histórico do git, um git revert de distância — esse é o arquivo; um commit de checkpoint antes de excluir o torna à prova de balas.
4. Arquivos não rastreados ou gitignorados: NUNCA rm diretamente — o histórico do git não pode recuperar o que nunca foi commitado. Esta é a linha de segurança de dados. Mova-os para o diretório de quarentena declarado do repositório (Passo 0.6) em vez disso. Se nenhum for declarado, crie um agora: .iteration-quarantine/ na raiz do repositório, adicionado ao .gitignore, declarado no documento de entrada com uma linha ("quarentena para arquivos não rastreados pendentes de exclusão — esvaziado manualmente pelo usuário"). Esvaziar a quarentena é ato do usuário — ofereça em um fechamento futuro, com seu próprio sim explícito; nunca silenciosamente.
5. Nunca descarte os DADOS reais do produto como se fossem resíduos de desenvolvimento. Estado do usuário/cliente, sessões salvas, arquivos reais de conteúdo do usuário parecem desordem e são a alma do produto. Quando um diretório pode ser qualquer um dos dois, trate-o como dados e mantenha-o; verifique antes de qualquer git rm.
6. Faça commit das exclusões em grupos temáticos; cada mensagem diz POR QUE + o que o substitui.
7. Verificações pós-exclusão (todas que se aplicam devem passar): se o repositório tiver uma suíte de teste, ela está verde; a busca por referências pendentes para cada módulo/símbolo excluído está vazia (uma importação de um arquivo excluído trava na inicialização — uma cicatriz real); o documento de entrada e os documentos de habilidade não fazem referência a nenhum caminho excluído.

TESTE DE SAÍDA: git status limpo, nenhum diretório em forma de arquivo existe — exceto diretórios que o documento de entrada declara como dados, recuperação ou quarentena (Passo 0.6) — busca por referências pendentes vazia, e a suíte de teste verde se existir.

Fase 3 — DOIS CANAIS DE PRONTIDÃO (necessidades diferentes; verificar separadamente)

Upload e ser continuável NÃO são o mesmo problema. Confundi-los é como um repositório é "enviado para a nuvem" enquanto seu estado real ainda vive em um log de chat. Verifique cada um por conta própria.

3a. Upload confirmado para a nuvem (o problema de TRANSPORTE)

1. Varredura de segredos apenas em arquivos RASTREADOS (sk-ant / ghp_ / gho_ / github_pat / AKIA / xox[baprs] / consumer_secret / access_token / Bearer / BEGIN PRIVATE KEY / formatos .env). Qualquer acerto → pare, limpe, re-varra.
2. Verifique git remote. Se NÃO houver remoto, o upload precisa de um que o USUÁRIO forneça — adicionar um remoto é uma alteração de configuração, então confirme com o usuário ou registre "nenhum remoto ainda — publicação adiada" e pule para 3b em vez de gerar erro em um comando git simples.
3. Com um remoto: mostre git log @{u}..HEAD --oneline + diffstat (recorra a "todos os commits locais" quando não houver upstream ainda) — exatamente o que sairá desta máquina.
4. Upload via o comando de upload confirmado do repositório (Passo 0.2) após o usuário confirmar; se o repositório não tiver nenhum, git push após o diffstat e um sim. Nunca auto-push.

3b. Retomada sem contexto (o problema de COMPLETUDE DE CONHECIMENTO) — o probe de inicialização a frio

1. Coloque UM leitor genuinamente livre de contexto no repositório — no Claude Code: spawn um subagente fresco (ferramenta Task); no Codex: execute um codex exec fresco ou uma nova sessão sem contexto anterior; em qualquer ambiente bare: abra uma nova sessão e cole APENAS o caminho do repositório mais as perguntas, nunca esta conversa. Dê a ele apenas o caminho do repositório e: "Leia este repositório a frio a partir de seu documento de entrada. Depois responda: (1) o que é este produto, em uma frase; (2) onde está o trabalho (concluído / próximo); (3) o que você faria a seguir e por quê; (4) nomeie três coisas que você nunca deve fazer aqui."
2. Avalie suas respostas em relação aos documentos canônicos do repositório. Se o repositório não tiver nenhum documento de entrada/canônico, criar um mínimo (o produto em uma frase, estado atual concluído/próximo, três nunca-faça) é parte deste fechamento — é o artefato que o probe avalia. Não execute o probe contra nada.
3. Cada resposta errada ou ausente é um BUG NO DOCUMENTO DE RETOMADA, não culpa do probe. Corrija (ou crie) o documento, re-execute com um NOVO leitor fresco. Faça um loop até que um leitor a frio pontue 4/4, no máximo 3 rodadas — se ainda falhar após 3, liste as lacunas restantes e passe a decisão para o usuário.

TESTE DE SAÍDA: probe passa 4/4. Só então "qualquer nova janela / máquina pode continuar" é um fato testado.

Fase 4 — BOOTSTRAP EM UM COMANDO (ensaiado, não assumido)

1. Garanta que o bootstrap do repositório (Passo 0.3) existe e está atualizado — idempotente, seguro para reexecutar: verifique as versões das ferramentas; configure a sincronização/config; instale dependências; execute a suíte de teste se existir; imprima o status atual + os NOMES de quaisquer segredos locais ausentes (nunca valores, por exemplo, "config.local.json ausente — necessário apenas para publicação ao vivo"); saia com código não zero em qualquer falha com um motivo de uma linha. Se nenhum bootstrap existir ainda, esta é a iteração para criar um.
2. ENSAIE-O: clone o repositório em um diretório temporário (da URL de origem, ou do caminho do repositório local quando não houver remoto ainda) e execute o bootstrap lá. Ele deve terminar verde com ZERO etapas manuais. Exclua o clone de ensaio após.
3. A história de nova máquina deve ser uma linha e VERDADEIRA após este ensaio: git clone <origin-url> <dir> && cd <dir> && <comando de bootstrap>. Se nenhum remoto existir ainda, observe que esta linha ainda não é verdadeira até que o usuário defina um — não a publique como se funcionasse.

TESTE DE SAÍDA: o clone de ensaio executa o bootstrap verde, sem intervenção manual.

Fase 5 — FECHAR + SEMEAR (continuidade)

1. Crie uma tag para a iteração: git tag iter-<N>-<slug> (anotada, resumo de uma linha). N = 1 + a contagem de tags iter-* existentes (git tag --list "iter-*"); o primeiro fechamento é iter-1.
2. Atualize o quadro de status / log com uma linha, se o repositório tiver um: o que foi destilado, quantos arquivos descartados, probe 4/4, bootstrap ensaiado.
3. Emita a SEMENTE DA PRÓXIMA ITERAÇÃO no chat: as perguntas em aberto que esta iteração trouxe à tona + um prompt de início copiável para o próximo slice (objetivo, critérios de aceitação e um lembrete para executar a barreira de fundamentação do repositório antes de construir, se tiver uma).

Iteração maior — quando a própria ESTRUTURA é substituída (mesmas regras, pele maior)

Uma reformulação estrutural — nova arquitetura, nova árvore de módulos, até mesmo "a abordagem antiga estava errada" — é ainda uma ITERAÇÃO de um organismo, não um recomeço. Ela mantém seu histórico git, suas decisões, suas lições; apenas a pele é nova. Recomeços sangram: toda vez que um projeto renasce em um repositório fresco, material de nível de lição é deixado para trás. Então:

• Cultive a nova estrutura NESTE REPOSITÓRIO junto com a antiga (padrão estrangulador): a nova árvore ganha testes e propriedade primeiro; a árvore antiga morre na Fase 2 apenas quando nada mais a referencia.
• Abrir um NOVO repositório é a exceção cara, não o padrão — requer uma decisão registrada declarando por que ESTE histórico deve ser abandonado, aprovada antes que qualquer arquivo seja movido.
• Mesmas cinco fases; o inventário de exclusão é apenas maior e o probe de inicialização a frio importa mais — os documentos da nova estrutura nunca encontraram um estranho.
• Se o nome do produto ou comando de entrada mudar, a história de uma linha da Fase 4 é atualizada na MESMA iteração. Dois nomes vivos é um bug de duas-verdades.

Barreiras (não negociáveis)

• A ordem das fases é o mecanismo de segurança: NUNCA descarte (Fase 2) antes da destilação (Fase 1) sair — no modo apenas descarte, a verificação pontual da Fase 1 no inventário é essa barreira.
• O inventário completo de exclusão é mostrado ao usuário, e NADA é excluído sem seu sim explícito. O agente nunca pressiona botões irreversíveis por conta própria.
• Arquivos não rastreados ou gitignorados são colocados em quarentena, nunca rm'd — o histórico do git não pode recuperá-los.
• A exclusão precisa de evidência de substituição, não de intuição. Realmente não tem certeza? Mantenha por MAIS UMA iteração e registre a dúvida.