r3xsean/see-it-through

Pegue uma alteração de código da solicitação do usuário até onde ela deve terminar, com outro modelo como revisor. O usuário decide duas vezes: a abordagem, no explainer, e o resultado, na ship message. Tudo entre isso é seu.

O outro modelo é o modelo mais novo, em orchestrator_capabilities, da família que o usuário nomeou, no esforço que ele nomeou. O mesmo modelo e esforço executam todas as idas e vindas, loop de código e revisão abaixo, exceto o debate de uma decisão chave. Se a família ou o esforço estiver faltando, peça por eles e não faça mais nada até que o usuário responda.

Um runner argumenta a abordagem no passo 3 em seu lugar (a skill back-and-forth's runner). A menos que o usuário nomeie um runner: o modelo Fable mais novo em médio, debatendo o outro modelo; para uma decisão chave, o modelo Fable mais novo em alto, debatendo o modelo Astra mais novo em alto no lugar do outro modelo. Uma decisão chave é aquela onde um gatilho na questão estrutural do design.md dispara e você pode declarar uma pergunta cuja resposta poderia mudar a abordagem. Quando o modelo de um runner ou de seu parceiro estiver indisponível, diga isso e argumente a abordagem você mesmo com o outro modelo.

1. Destino e regras

Descubra onde a alteração termina: uma alteração local testada, um branch enviado, um PR aberto, mesclado ou implantado. Pergunte apenas quando não estiver claro e a resposta mudar o trabalho. Dizer "see it through" não aprova push, PR ou deploy; a aprovação na ship message sim.

As regras do repositório que você está alterando, e qualquer arquivo de processo que o usuário indicar, vencem onde diferirem desta skill.

Uma alteração já construída. Quando o usuário disser que a alteração já está pronta, o que está construído é a abordagem, e a ship message é a primeira aprovação: não envie explainer e não execute back-and-forth. No lugar dos passos 2 e 3:

• Fixe a base: para um branch não mesclado, sua base de mesclagem com o branch no qual ele mescla, obtida após sua última mesclagem daquele branch; uma vez mesclado, o commit anterior à alteração. Pergunte quando não estiver claro. Quando a alteração já estiver mesclada, o destino é para onde os commits de acompanhamento desta execução vão; pergunte quando não estiver claro.
• Escreva a solicitação a partir das palavras do usuário e do que a alteração diz sobre si mesma (mensagens de commit, texto do PR), marcando o que você inferiu.
• Encontre as verificações que falham em uma worktree da base e passam na alteração, começando com os testes que a alteração já possui (execute-os na base com apenas os hunks de teste e infraestrutura da alteração aplicados), e escreva uma apenas para um comportamento prometido que nenhum deles prova; para uma alteração sem falha a mostrar, como uma otimização ou refatoração, uma verificação do que ela promete. Defina o nível como o passo 2 faz. Mantenha como linha de base de aceitação, como o passo 4 mantém, o menor número dessas verificações que provam cada comportamento que a alteração promete, anotando quais foram escritas após a alteração; os outros testes da alteração permanecem abertos para simplify.md.
• Escreva a abordagem como construída em um arquivo: o que mudou, o grounding do design.md e sua questão estrutural respondida sobre o que foi construído, e a verificação de falha do passo 3.

Em seguida, continue no passo 4 mostrando a reprodução passando, e execute o loop de código com aquela base e aquele arquivo como sua Abordagem. A ship message diz que nenhum explainer foi aprovado, e carrega qualquer alternativa estrutural e qualquer descoberta que mude o que o usuário obtém.

2. Reproduzir

Para um bug, reproduza-o na base antes de escrever uma correção: um teste que falha e, quando um usuário pode ver o bug, o produto em execução mostrando-o, capturado como capture.md diz, manualmente quando o fluxo de verificação ainda não pode capturar. Para uma funcionalidade, escreva o que o usuário deve ver ou ser capaz de fazer. Quando você não puder reproduzir um bug, avise o usuário antes de construir uma correção, e escreva qualquer coisa que você disser sobre isso como "da leitura do código (não testado)". Uma verificação que não encontra nada conta apenas quando você a viu encontrar a coisa quando ela estava lá.

Não construa guarda para um caminho de falha que você não reproduziu; liste-o no explainer como um acompanhamento.

Reproduza e prove através da skill de verificação do repositório: .agents/skills/verify/ no repositório, ou onde o AGENTS.md do repositório a coloca. Quando não houver nenhuma, ou ela não cobrir o fluxo que você precisa, reproduza manualmente por enquanto e torne a construção dessa cobertura com a skill make-verifiable parte da abordagem.

Em seguida, defina o nível. Completo quando o comportamento alterado atinge persistência, concorrência, autorização, migrações, um contrato público, efeitos destrutivos ou propriedade de estado compartilhado, ou quando você ainda não pode dizer como o código alterado é alcançado ou quão bem os testes o cobrem; julgue pelos chamadores e escritores de estado que você encontrar, não por nomes de arquivo. Leve caso contrário. Uma execução leve que encontra um destes se torna completo.

3. Design e o explainer

Leia design.md e faça o que ele pede antes de escolher uma abordagem. Em uma execução completa, vá e volte com o modelo sobre a abordagem (a skill back-and-forth), com as estimativas de proporção do design.md em seu Contexto como premissas a verificar e uma versão menor e nenhuma mudança entre as opções; em uma execução leve, faça isso apenas quando os gatilhos do design.md dispararem ou as abordagens fortes diferirem materialmente, e caso contrário escreva a abordagem você mesmo. Dê ao runner, no Contexto, seu grounding com suas referências, o que você reproduziu e o que apenas leu, e um caminho para seu registro no scratchpad ou pasta temporária da sessão; na Pergunta, que você escreve a partir da solicitação, peça também por onde a alteração cai, chamadores e casos irmãos incluídos, os casos de aceitação, e o que ela deixa para você. Quando uma questão de design for um fato que você poderia observar executando algo, resolva-a com um experimento descartável em um checkout isolado ou dados de rascunho, não perguntando ao usuário; o experimento não entrega nada.

Em seguida, escreva a verificação de falha: percorra as Condições no cabeçalho resumido da skill code-loop, mais quem dependia do comportamento que você está alterando, e para cada uma que se aplicar, nomeie o teste que a cobrirá ou a limitação que você aceita.

Envie ao usuário o explainer, em linguagem simples, sob estes cabeçalhos, em ordem. Diga cada coisa uma vez.

• O problema: o que um usuário vê hoje, quem o encontra e com que frequência (observado ou estimado; sem relatos significa desconhecido, não raro), por que é importante, e sua reprodução, com sua captura quando houver uma; para uma funcionalidade, o que está faltando hoje. Quando o usuário pediu a alteração, abra com as palavras dele.
• Por que acontece: a causa, em termos simples; para uma funcionalidade, o que atrapalha hoje. Deixe este cabeçalho de fora para uma funcionalidade quando nada atrapalhar.
• O que muda: o que o usuário verá ou poderá verificar quando estiver pronto, e o que está fora do escopo. Onde algo que mudaria o trabalho estiver faltando, peça aqui.
• A abordagem: o que muda no código e onde, como você vai provar, incluindo qualquer trabalho make-verifiable e quais verificações acompanham a alteração ou permanecem como evidência, quanto custa para entregar e manter e por que isso vale o alcance e o dano sob O problema, e as entradas de verificação de falha que um revisor se importaria.
• Alternativas consideradas: cada alternativa forte, a opção estrutural do design.md entre elas sempre que uma credível existir, cada uma com por que perdeu.
• O que um revisor pode perguntar: cada pergunta provável, com sua resposta.

Em seguida, pare: não construa nada até que o usuário aprove. Uma aprovação simples em qualquer redação permite construir. Qualquer outra coisa vai palavra por palavra para o mesmo back-and-forth como uma troca adicional, passando seu limite de trocas, e volta como um explainer revisado; pare novamente. Em uma execução leve sem back-and-forth, revise o explainer você mesmo e pare novamente.

A aprovação cobre o explainer como escrito. Quando um teste, uma demonstração ou uma revisão mudar o que o usuário obtém, seu comportamento visível, compatibilidade, escopo, a ação que você tomará para entregá-lo, ou uma troca que o explainer aceitou, cite a frase que ele falsifica, resolva com o modelo, envie um explainer revisado que diga o que mudou, e pare novamente. Descobertas menores, como usar um helper interno diferente, vão na ship message sob "o que mudou desde".

4. Construir e provar

Antes de mudar o comportamento, mantenha a reprodução e toda verificação de aceitação que pode ser executada antes da alteração existir: faça commit das que o explainer entrega, e salve o restante, ou todas quando nada for commitado, como um patch fora do repositório. Juntos eles são a linha de base de aceitação, e tudo é executado novamente no candidato final: qualquer edição posterior vai para o loop de código e a ship message com seu diff e se muda o comportamento prometido.

Construa a abordagem aprovada, na ordem que o design.md define. Quando a alteração modificar um fluxo que a skill de verificação cobre, atualize esse fluxo na mesma alteração. Mostre a reprodução do passo 2 passando, através da skill de verificação e no produto em execução quando o usuário puder vê-la. Em seguida, simplifique o diff como simplify.md diz. Em seguida, execute um loop de código com o modelo no diff completo (a skill code-loop), dando a ele a solicitação do usuário, ou o resumo que a representa, como a Solicitação, o explainer como a Abordagem, com o registro do runner quando houver um, a linha de base de aceitação como a Aceitação, e o nível.

No candidato final, quando um usuário puder ver ou fazer o que mudou, capture através do fluxo de verificação, estendendo o fluxo com make-verifiable quando não puder, e para um bug capture o mesmo cenário na base através do mesmo fluxo, para que o antes e depois correspondam. Escolha, faça e revise a captura como capture.md diz, e verifique se mostra o que você vai dizer que mostra. Uma captura mostra a alteração e as verificações a provam, então uma captura da base ou de uma execução falha nunca representa uma aprovação. Uma alteração sem nada para ver não recebe captura.

5. Redação

Rascunhe o texto do PR, issue ou release a partir dos templates do projeto, com as capturas onde o template tiver espaço para elas, ou sob um cabeçalho próprio. No GitHub, anexe-as quando publicar com gh pr create --attach (ou gh pr edit) a menos que o repositório tenha sua própria ferramenta; quando sair com código diferente de zero, procure o PR antes de tentar novamente, pois ele já pode existir. Antes de qualquer texto público que declare um fato (uma descrição, uma resposta, uma atualização de status), um revisor novo do modelo verifica-o contra a evidência, as capturas (uma gravação como seus quadros e relatório de ritmo) e o diff: toda afirmação verdadeira e fundamentada, toda caixa marcada verdadeira. Corte uma afirmação que a evidência não fundamenta; não a atenue.

Antes de cada push, reexecute a verificação por trás de cada caixa marcada e cada afirmação, e refaça cada captura, que a alteração desde então poderia afetar.

6. Ship message

Envie ao usuário: um resumo de duas ou três frases do explainer, o que mudou desde então, a evidência, as capturas, a redação, o diff e a ação exata que você tomará na aprovação. Quando o loop de código terminou com disputas não resolvidas, lidere com elas: cada afirmação, o que cada lado mostrou e o que aprovar entrega com ela. Antes de enviá-la, refaça a verificação de sobreposição do design.md. Pare até que a aprovem.

7. Até o destino

Tome a ação aprovada, então leve a alteração ao seu destino:

• Antes de cada push e antes de agir em uma notificação, busque a cabeça remota e verifique o status atual da alteração. Construa sobre pushes de outros, comparando árvores em vez de hashes de commit; não substitua o trabalho deles com uma versão local desatualizada. Quando a alteração chegar, fechar ou for substituída pela versão de outra pessoa, compare o que alcançou o destino com sua última cabeça verificada e descobertas abertas. Relate o que difere ou não chegou, sem readicionar o que eles removeram de propósito.
• Toda descoberta de revisão, inline ou no corpo de uma revisão, lida por completo, recebe uma correção ou uma razão de uma linha; uma que também acontece na base é julgada como code-loop julga uma descoberta pré-existente. Uma correção que muda comportamento recebe um loop de código.
• Quando um fato provar que o texto postado está errado, corrija o texto.
• Uma solicitação que mude o escopo ou a abordagem volta ao passo 3 e, uma vez construída, para uma nova ship message; uma que se aplique além desta alteração vai para o usuário quando chegar, com seu link: fazê-lo aqui não o faz em outro lugar.
• Para um deploy, execute o fluxo de verificação contra o que está implantado.

8. Lições

Quando o usuário, um revisor de PR ou qualquer coisa depois da entrega pegou um problema que o loop de código perdeu, ou o loop de código encontrou um bloqueador ou deveria, adicione uma entrada a .agents/lessons/log.md no repositório que você alterou; para um repositório que o usuário não possui, na pasta que contém seu processo para ele. Cada entrada: a data, a alteração, o que foi pego e por quem, o módulo, a classe de bug e a causa.

Em seguida, leia o log. Uma lição que uma verificação poderia pegar, vista duas vezes, torna-se uma verificação de lint, tipo, teste ou verificação; uma que precisa de julgamento, vista duas vezes, torna-se uma linha no AGENTS.md do repositório; duas entradas em um módulo, ou duas de uma classe de bug em quaisquer módulos (como estado que outra operação muda durante um await), tornam-se uma questão estrutural, nomeando a causa que compartilham antes que qualquer refatoração seja proposta. Liste cada uma como um acompanhamento em sua mensagem final; uma refatoração executa como seu próprio see-it-through.

Concluído quando a alteração está em seu destino, ou quando você relatou o bloqueador exato e o que resta, e a entrada de lições, se uma for devida, está escrita.