fhajjej-ship-it/loop-it

Loop It (Ciclo It)

Transforme um objetivo de codificação aberto em um ciclo delimitado e verificável. Loop It também é uma biblioteca de ciclos: escolha o ciclo inicial certo, adapte-o ao contexto do usuário e acompanhe o progresso para que o próximo ciclo seja óbvio.

Decisão

Primeiro, decida qual modo o usuário precisa:

• Encontrar na biblioteca: selecione um ciclo pré-definido para o objetivo do usuário.
• Próximo a partir do progresso: inspecione .loop-it/progress.json ou .loop-it/LOOP.md e recomende o que fazer a seguir.
• Apenas projetar: produza um prompt de ciclo reutilizável ou um arquivo de ciclo local ao projeto.
• Executar agora: execute uma iteração delimitada por vez, verifique-a e decida se outra iteração é justificada.
• Exportar/instalar: adapte o mesmo ciclo para Codex, Claude Code, Cursor ou outro agente compatível com SKILL.md.

Se a tarefa for vaga, não faça um questionário amplo de descoberta. Primeiro, recomende o melhor ciclo da biblioteca e declare a suposição. Faça no máximo três perguntas direcionadas apenas quando o objetivo, a verificação de sucesso, o escopo do repositório ou o limite de aprovação estiverem realmente bloqueados.

Contrato

Cada ciclo precisa destes campos antes da execução:

• Objetivo: o resultado concreto, não um tema.
• Escopo: repositório, arquivos, área de funcionalidade, fonte de dados ou ambiente.
• Verificação de sucesso: comando, benchmark, inspeção manual, critério de revisão ou limite mensurável.
• Limite de iterações: número máximo de passes ou orçamento de tempo.
• Condições de parada: sucesso, nenhuma melhoria significativa, falha repetida, acesso bloqueado, ação insegura ou exigência de aprovação.
• Evidência: o que registrar após cada passe.
• Pontos de aprovação: gravações em produção, mensagens externas, pagamentos, operações git destrutivas, credenciais, implantações ou alterações irreversíveis de dados.

Recuse quando o ciclo solicitado for apenas "continue melhorando" sem uma verificação. Ofereça um ciclo menor com uma verificação clara.

Selecionar um Ciclo

Prefira a biblioteca pré-definida a criar um ciclo do zero.

Use o script seletor quando disponível:

node <skill-dir>/scripts/select-loop.mjs list
node <skill-dir>/scripts/select-loop.mjs search "failing ci"
node <skill-dir>/scripts/select-loop.mjs recommend --goal "fix failing checkout test"
node <skill-dir>/scripts/select-loop.mjs next --cwd <project>

Resolva <skill-dir> para a pasta desta skill. No Claude Code, ${CLAUDE_SKILL_DIR} pode estar disponível. Em outros agentes, localize o diretório que contém este SKILL.md.

Ao selecionar:

1. Verifique .loop-it/progress.json primeiro quando o usuário perguntar o que fazer a seguir.
2. Se não houver progresso, compare o objetivo do usuário com references/library/loops.json.
3. Recomende um ciclo, mais no máximo duas alternativas.
4. Explique a correspondência em uma frase.
5. Faça as principais perguntas do ciclo apenas se necessário.
6. Se nenhum ciclo da biblioteca servir, projete um ciclo personalizado e diga que ele deve ser considerado para a biblioteca depois que se mostrar útil.

Leia references/library/loops.json apenas quando o script seletor não estiver disponível ou a inspeção manual for necessária. Leia references/loop-template.md quando a tarefa precisar da forma de estado durável genérica.

As categorias atuais da biblioteca incluem:

• Ticket para correção verificada: reproduzir, diagnosticar, corrigir, adicionar cobertura de regressão, verificar.
• Reparo de CI com falha: inspecionar saída com falha, reproduzir, corrigir, reexecutar a verificação com falha.
• Varredura de documentação: comparar documentação com implementação, atualizar documentação desatualizada, verificar exemplos ou links.
• Avaliação de produto: definir cenários e critérios, testar, corrigir falhas, reexecutar verificações afetadas e completas.
• Ciclo de desempenho: medir linha de base, fazer uma alteração focada, medir novamente, manter apenas ganhos comprovados.
• Ciclo de reparo de revisão: revisar diff, corrigir descobertas bloqueadoras, reexecutar verificações, repetir até que apenas riscos aceitos permaneçam.
• Ciclo de configuração limpa: começar de um ambiente limpo, seguir a configuração documentada, corrigir suposições ocultas, tentar novamente de forma limpa.
• Prontidão para lançamento: verificar pacote, implantação ou caminhos de instalação pública antes de publicar.
• Ciclos de polimento de UX, atualização de dependências, endurecimento de segurança, contenção de refatoração e cobertura de lacunas de teste.

Projetar o Ciclo

Use esta estrutura para prompts de ciclo e arquivos de estado:

1. Declare o objetivo e os não-objetivos.
2. Defina a ação repetida em um ciclo enxuto: inspecionar, agir, verificar, registrar, decidir.
3. Nomeie o comando exato de verificação ou a verificação manual.
4. Defina o limite de iterações e as condições de parada.
5. Defina o que o relatório final deve incluir.

Mantenha a versão 1 estreita: um repositório, uma função principal, uma verificação principal de sucesso. Adie agendamento, painéis, orquestração multiagente e automação de produção até que um ciclo manual tenha se mostrado útil.

Quando um arquivo de estado durável for útil, crie .loop-it/LOOP.md a partir de references/loop-template.md ou execute:

node <skill-dir>/scripts/create-loop.mjs --name "Nome do ciclo" --objective "Resultado concreto" --check "Comando de verificação ou critério"
node <skill-dir>/scripts/create-loop.mjs --from failing-ci-repair

Arquivos de ciclo baseados em biblioteca também criam .loop-it/progress.json a menos que --no-progress seja passado.

Executar o Ciclo

Para cada iteração:

1. Releia o objetivo, a verificação de sucesso, o limite e os pontos de aprovação.
2. Inspecione apenas o contexto necessário para a próxima ação delimitada.
3. Faça a menor alteração crível.
4. Execute a verificação mais restrita relevante primeiro, depois verificações mais amplas apenas se necessário.
5. Registre evidências em .loop-it/LOOP.md quando um arquivo de estado existir e atualize .loop-it/progress.json quando presente.
6. Decida: parar, continuar, pedir aprovação ou relatar bloqueio.

Pare imediatamente quando continuar exigir suposições ocultas sobre segurança, credenciais, dados de produção, faturamento, mensagens ao usuário, operações git destrutivas ou aprovação de implantação.

Não descreva um ciclo exaurido, bloqueado ou parcialmente verificado como completo. Diga exatamente qual condição o parou e quais evidências existem.

Exportar

Use o mesmo texto do ciclo entre ferramentas, mudando apenas a invocação:

• Codex: instale em .agents/skills/loop-it/ ou como plugin Codex, depois invoque com $loop-it.
• Claude Code: instale em .claude/skills/loop-it/, depois invoque com /loop-it.
• Cursor: instale em .cursor/skills/loop-it/, depois invoque do chat do Agent com /loop-it ou pedindo um ciclo. Use regras do Cursor para convenções sempre ativas do projeto, não para este ciclo procedural.

Ao exportar, mantenha um corpo de ciclo canônico e evite sintaxe específica da ferramenta, a menos que a ferramenta exija.