m1nga/loop-system-architect

Arquiteto de Sistemas de Loop

Transforme uma tarefa repetitiva em um sistema de controle observável que pode executar, provar seu resultado, se recuperar após interrupção e melhorar sem reescrever seu próprio propósito.

Escolha o modo

• Auditoria: inspecione um fluxo de trabalho existente e relate partes ausentes ou em malha aberta. Não edite a menos que solicitado.
• Design: produza o contrato, esquema de estado, grafo de papéis, avaliações e design de tempo de execução.
• Operacionalizar: implemente o controlador, adaptadores, persistência, evidências e caminho de execução com um comando.
• Evoluir: analise execuções concluídas, valide uma melhoria proposta de loop/conhecimento/habilidade e promova ou rejeite.

Quando o usuário pedir para "construir" ou "fazer funcionar", inclua Operacionalizar. Um plano em Markdown sozinho não é um loop operacional.

Comece da realidade atual

1. Leia as instruções do repositório e os artefatos que o usuário colocou no escopo.
2. Inspecione as ferramentas reais, pontos de entrada, arquivos de estado, testes, agendadores, CLIs de agente e árvore de trabalho suja.
3. Separe a entrada autoritativa atual do material de referência. Não use memória de modelo para preencher lacunas.
4. Classifique o loop:
   • Terminal: um objetivo com uma linha de chegada demonstrável.
   • Recorrente: toda execução termina, enquanto o monitor/serviço continua até ser aposentado.
5. Informe o que existe, o que está faltando e o que é apenas afirmado antes de qualquer alteração.

Para uma auditoria completa, leia audit-rubric.md.

Exija um loop de controle fechado

Identifique e conecte todos estes:

1. objetivo e proprietário;
2. condição de conclusão ou condição de sucesso por execução;
3. fronteira da fonte autoritativa e proveniência;
4. gatilho e pré-verificação barata;
5. sensor e sinal coletado;
6. comparador, janela e limite/regra;
7. controlador e espaço de decisão finito;
8. atuador e o caminho que retorna o novo resultado ao sensor;
9. estado persistente, cursor, registro de eventos e armazenamento de evidências;
10. responsabilidades do orquestrador, executor e verificador independente;
11. descoberta aberta de capacidade/habilidade e criação de habilidades candidatas;
12. limites de autoridade e campos protegidos;
13. avaliações de aceitação e evidências exigidas;
14. novas tentativas, tempos limite, backoff, classificação de falhas e reversão;
15. idempotência, deduplicação, bloqueio de concorrência e ponto de estrangulamento de efeitos colaterais;
16. orçamentos de token, custo, turno e tempo de parede;
17. observabilidade, alertas e um estado de sucesso sem operação;
18. substituição direta da verdade ativa substituída;
19. destilação de experiência e promoção controlada;
20. condições de parada, pausa, interrupção e aposentadoria.

Feedback ausente sensor-para-atuador significa malha aberta. Estado persistente ausente significa um prompt repetido. Evidência de verificador ausente significa conclusão autoafirmada. Controlador/gatilho ausente significa um procedimento que humanos devem operar.

Perfil mínimo

Nem todo loop precisa de todos os vinte elementos. Para um loop de operador único, nível cron — um usuário, uma máquina, baixo raio de explosão, sem efeitos colaterais compartilhados — um contrato é suficiente com oito:

1. objetivo e proprietário;
2. condição de sucesso (conclusão ou por execução);
3. gatilho e pré-verificação barata;
4. atuador e seu caminho de efeitos colaterais;
5. estado persistente e cursor;
6. idempotência/deduplicação no caminho de efeitos colaterais;
7. observabilidade: onde ver o último resultado e a próxima ação;
8. condição de aposentadoria.

Declare as omissões explicitamente em vez de deixá-las em branco: defina learning.enabled: false, e defina capabilities.discovery: "none" com um campo reason. O linter aceita ambos. Veja loop.contract.minimal-example.json para um exemplo de contrato mínimo aprovado. Atualize para o contrato completo quando o loop ganhar efeitos colaterais compartilhados, um segundo operador, locatários externos ou qualquer forma de automodificação.

Produza um pacote de loop

Adapte os nomes ao repositório, mas mantenha um contrato canônico legível por máquina e um registro de estado. Pacotes de loop, estado e evidências residem no projeto do usuário, nunca dentro deste pacote de skill. O pacote padrão é:

loop/
├── LOOP-CONTRACT.md          contrato operacional legível por humanos
├── loop.contract.json        contrato canônico legível por máquina
├── RUN-STATE.json            execução atual, cursor, tentativas, próxima ação da máquina
├── events/                   eventos de execução somente anexação ou armazenamento de eventos equivalente
├── evidence/                 recibos legíveis pelo verificador
├── evals/                    verificações de aceitação determinísticas e semânticas
├── knowledge/                conhecimento promovido tipado, não logs brutos
├── candidates/               lições não promovidas e alterações de habilidades
└── scripts/run-loop          controlador de um comando ou equivalente nativo do projeto

Use loop-contract.md para o contrato de campo. Copie loop.contract.template.json, preencha todos os placeholders, depois execute:

python3 scripts/loop_lint.py /caminho/para/loop.contract.json

Use a cópia dentro desta skill quando o projeto não tiver feito o vendoring do linter. Se nada puder ser gravado em disco, produza o contrato e o controlador como texto copiável e diga o que ainda precisa ser colocado em disco antes que o loop esteja operacional.

Construa o controlador, não apenas as instruções

O controlador deve fazer com que uma invocação avance o loop sem pedir ao usuário para copiar e colar entre agentes:

1. adquira um bloqueio de concorrência e derive uma chave de idempotência;
2. carregue e valide o contrato e o estado;
3. verifique hashes de fonte congelada ou autoridade de fonte atual;
4. execute o gatilho/pré-verificação barato e registre um sucesso sem operação quando não houver trabalho;
5. resolva as capacidades necessárias;
6. crie um pacote de contexto mínimo para o orquestrador/executor;
7. execute em um espaço de trabalho isolado quando alterações forem possíveis;
8. capture saídas, custos, chamadas de ferramenta, diffs e evidências;
9. execute um verificador independente que não pode certificar suas próprias escritas;
10. em caso de falha, classifique e direcione um reparo limitado, nova tentativa, reversão ou parada;
11. em caso de aprovação, promova atomicamente o resultado e atualize o estado atual;
12. anexe um evento/recibo imutável;
13. invoque a destilação apenas quando seu gatilho for satisfeito;
14. libere o bloqueio e exponha a próxima ação executável pela máquina.

Independência mínima do verificador, por mecanismo:

• Claude Code (ou qualquer runtime com subagentes): execute o verificador como um subagente de contexto novo que recebe apenas o contrato, as verificações de aceitação e os caminhos de evidência — não a conversa do executor.
• Nenhum mecanismo de subagente: execute o verificador como um processo separado ou invocação separada que releia as evidências do disco e retorne um veredito contra as verificações de aceitação.
• Nenhum disponível: o mesmo contexto verificando seu próprio trabalho é auto-revisão — desempenho, não verificação. Diga isso na auditoria em vez de rotulá-lo como verificador.

Prefira código determinístico para gatilhos, transições de estado, verificações de esquema, permissões, novas tentativas, hashes e promoção. Use LLMs para julgamento, planejamento, diagnóstico e conteúdo que não pode ser decidido mecanicamente.

Descubra ou crie habilidades sem uma lista branca estática

Use descoberta aberta com execução controlada:

1. Derive um contrato de capacidade da tarefa: entrada, saída, efeitos colaterais, evidências, risco.
2. Pesquise habilidades instaladas e capacidades do projeto por metadados e adequação ao contrato.
3. Inspecione proveniência e dependências; não importe identidade de projeto incorporada como verdade.
4. Coloque em sandbox uma habilidade candidata e execute avaliações específicas da capacidade.
5. Se nenhuma se encaixar, crie uma habilidade candidata isoladamente com seus próprios exemplos e avaliações.
6. Promova uma versão somente depois que ela passar por verificações de segurança, privacidade, funcionalidade e regressão.
7. Registre localmente por padrão. A publicação externa segue a política separada do ambiente proprietário.

Descoberta aberta não concede autoridade aberta. Mandatos, escopo de dados, política de efeitos colaterais e permissões de tempo de execução ainda restringem toda habilidade.

Destile experiência em conhecimento utilizável

Nunca alimente um log sempre crescente para todo agente. Mantenha evidências brutas, resumos episódicos, lições candidatas, conhecimento canônico, habilidades processuais e avaliações separados.

Execute o caminho de promoção:

rastreamento + resultado
→ episódio normalizado
→ lição candidata
→ deduplicar e verificar conflitos
→ reproduzir contra execuções anteriores e contraexemplos
→ sombra ou canário
→ promover uma versão
→ monitorar as próximas execuções
→ manter ou reverter

Ative a destilação em caso de falha repetida, trabalho manual repetido, desvio, regressão de custo, evidencias de resultado significativo ou um tamanho de amostra configurado — não apenas porque o tempo passou. Leia distillation.md antes de projetar ou alterar a camada de aprendizado. Se uma skill de destilação dedicada (como experience-pack) estiver instalada, deixe-a possuir o fluxo de trabalho de destilação; esta skill projeta o loop que a invoca.

O processo de evolução pode melhorar SOPs, gatilhos, empacotamento de contexto, scripts, habilidades, recuperação e limites operacionais dentro da autoridade delegada. Ele não pode reescrever silenciosamente o objetivo, a fronteira da fonte, a fronteira de locatário/privacidade, o modelo de autoridade ou a avaliação que define o sucesso.

Substitua a verdade ativa limparmente

Para qualquer atualização aceita:

1. calcule o grafo de impacto em contrato, esquema de estado, código, testes, documentação, visualizações e habilidades;
2. declare SUBSTITUI, REMOVE e MANTÉM;
3. atualize todos os dependentes;
4. remova redação e valores substituídos da recuperação ativa;
5. execute varreduras de contradição/valor obsoleto;
6. execute avaliações de caminho feliz e de falha afetadas;
7. execute uma sonda de contexto zero que deve recuperar exatamente uma resposta atual;
8. promova atomicamente; retenha versões anteriores apenas no controle de versão/histórico de eventos, não no contexto ativo.

Calibre a autonomia

• Execute automaticamente ações reversíveis e limitadas quando a verificação determinística e independente for aprovada.
• Use canário, sombra, verificação dupla e reversão para ações automatizadas de maior risco.
• Pare para o usuário apenas quando a autoridade estiver faltando, uma decisão necessária mudar o objetivo, ou a ação for materialmente irreversível e não já autorizada.
• Nunca torne a aprovação humana rotineira um atuador oculto em um loop anunciado como autônomo.

Verifique a conclusão

Não chame o loop de operacional até que todos sejam verdadeiros:

• um comando ou evento configurado pode avançá-lo sem transporte de prompt;
• a recuperação de interrupção retoma do estado persistido sem refazer trabalho aceito;
• gatilhos duplicados não podem duplicar efeitos colaterais;
• falha do verificador causa reparo limitado ou uma parada limpa;
• ambos os caminhos de sucesso e falha fechada têm evidências;
• uma execução sem trabalho termina com sucesso e de forma barata;
• o status atual, último resultado, custo, falha aberta e próxima ação são observáveis;
• um candidato de evolução foi reproduzido e promovido ou corretamente rejeitado (dispensado sob o perfil mínimo com learning.enabled: false);
• um agente de contexto zero pode explicar o contrato atual e a próxima ação a partir dos arquivos ativos sozinho.

Relate separadamente: o que está implementado, o que foi exercitado, o que permanece dormente por falta de um sensor ativo e o que ainda requer a autoridade do usuário.