improve

# improve — audite com um modelo forte, execute com modelos baratos `improve` é uma skill de agente (formato Agent Skills) que audita qualquer codebase e escreve planos de implementação para outros agentes executarem. A premissa: gaste seu modelo mais capaz na parte onde a inteligência se acumula — entender o codebase, julgar o que vale a pena fazer, escrever a especificação — e entregue a execução para modelos mais baratos. A skill nunca implementa nada por si mesma; o plano é o produto. ``` você → /improve (modelo caro, aconselha) plans/ → 001-fix-n-plus-one.md (especificações autocontidas) outro agente → implementa, testa, entrega (modelo barato, executa) ``` ## Instalação ```bash npx skills add shadcn/improve ``` Funciona em qualquer agente que suporte o formato Agent Skills. Os planos são markdown simples, então qualquer agente ou humano pode usá-los. ## Comandos - `/improve` — auditoria completa → descobertas priorizadas → planos - `/improve quick` — passada barata: pontos críticos, principais descobertas apenas - `/improve deep` — exaustivo: cada pacote, cada categoria - `/improve security` — auditoria focada (também perf, testes, bugs, ...) - `/improve branch` — audita apenas o que o branch atual altera - `/improve next` — sugestões de recursos, para onde levar o projeto - `/improve plan <descrição>` — pule a auditoria, especifique uma coisa - `/improve review-plan <arquivo>` — critique e aperte um plano existente - `/improve execute <plano>` — despache um executor mais barato, revise seu trabalho - `/improve reconcile` — atualize o backlog: verifique, desbloqueie, retire - `--issues` — também publique planos como issues do GitHub ## Primeira execução típica 1. Abra seu agente no repositório e execute `/improve` (ou `/improve quick` para manter barato). 2. Ele mapeia o repositório, audita e retorna uma tabela de descobertas. Responda com as que você quer planejadas, ex. "planeje 1, 3 e 5". 3. Os planos caem em `plans/` — um arquivo cada, mais um índice com ordem recomendada. Eles são feitos para serem revisados. 4. Entregue um plano a qualquer agente ("implemente plans/001-*.md"), ou deixe a skill executá-lo: `/improve execute 001` despacha um modelo mais barato em uma worktree isolada, revisa o diff contra o plano e reporta um veredito. O merge continua sendo sua decisão. 5. Na próxima sessão, `/improve reconcile` limpa o backlog: verifique o que foi entregue, atualize o que mudou, desbloqueie o que travou. Antes de um PR, `/improve branch` limita o mesmo processo apenas ao que o branch altera. ## Como funciona - **Recon.** Mapeia o repositório: stack, convenções e comandos exatos de build/test/lint, que se tornam portões de verificação em cada plano. Também ingere documentos de intenção e design quando presentes — ADRs (`docs/adr/`), PRDs, `CONTEXT.md`, `DESIGN.md`, `PRODUCT.md` — para que tradeoffs decididos não sejam re-sinalizados, sugestões de direção permaneçam fundamentadas na intenção declarada do produto, e os planos usem o vocabulário do próprio repositório. - **Auditoria.** Distribui subagentes paralelos em nove categorias: correção, segurança, performance, cobertura de testes, dívida técnica, dependências e migrações, DX, docs e direção (sugestões de recursos devem citar evidências do próprio repositório). Cada descoberta carrega evidência `file:line`, impacto, esforço e confiança. - **Validação.** Como subagentes super-reportam, o conselheiro relê cada local citado antes de mostrar qualquer coisa; falsos positivos são descartados, atribuições erradas corrigidas, rejeições registradas. - **Priorização.** Descobertas caem em uma tabela ordenada por alavancagem (impacto ÷ esforço, ponderado por confiança). Você escolhe o que vira plano. - **Plano.** Um arquivo por descoberta selecionada em `plans/`, com índice, ordem de prioridade e grafo de dependências. ## O que torna os planos executáveis Os planos miram o executor plausível mais fraco — um modelo que nunca viu a sessão do conselheiro e pode ser bem menor. Três propriedades carregam isso: - **Autocontido.** Todo contexto é embutido: caminhos de arquivo exatos, trechos de código do estado atual, convenções do repositório com um arquivo exemplar, comandos verificados. Sem "como discutido acima". - **Portões de verificação.** Cada passo termina com um comando e sua saída esperada; critérios de conclusão são verificáveis por máquina, então o executor nunca precisa julgar sucesso. - **Limites rígidos.** Listas explícitas de fora de escopo e condições de PARADA ("se X, pare e reporte") em vez de deixar um modelo pequeno improvisar quando a realidade não corresponde ao plano. Cada plano carimba o commit git contra o qual foi escrito, para que executores possam rodar uma verificação mecânica de desvio antes de tocar em qualquer coisa. ## Fechando o ciclo - **`execute <plano>`** gera um subagente executor mais barato em uma worktree git isolada, entrega o plano, então revisa o resultado como um tech lead — re-executa cada critério de conclusão, verifica conformidade de escopo, lê o diff contra a intenção. Veredito: aprovar (merge continua sendo sua decisão), enviar de volta para revisão (máx. 2 rodadas), ou bloquear e refinar o plano. - **`reconcile`** processa o que aconteceu desde então: verifica se planos DONE ainda valem, investiga BLOCKED e reescreve em torno do obstáculo, atualiza planos desatualizados, retira descobertas corrigidas independentemente. - **`--issues`** publica planos como issues do GitHub com o mesmo corpo autocontido, para que qualquer agente ou humano possa pegá-los onde o trabalho já vive. ## Regras rígidas - Nunca modifica o código-fonte em si. As únicas escritas vão para `plans/`; executores editam apenas em worktrees descartáveis, e o merge é sempre seu. - Nunca executa comandos que mutam a árvore de trabalho — apenas leitura, busca e análise somente-leitura. - Nunca reproduz valores secretos; apenas locais e tipos de credenciais, rotação sempre recomendada. - Quando pedido para implementar, recusa e aponta para o plano (ou oferece `execute`). ## Licença MIT © shadcn