Bottleneck Lens

Lente de Gargalo (Bottleneck Lens)

Encontre o gargalo. Prove a melhoria.

Mantenha a coleta local; não faça upload de código-fonte, traces ou relatórios por padrão. As instruções portáteis e scripts agrupados não exigem um fornecedor de agente específico. Resolva caminhos agrupados relativos a este SKILL.md. A CLI requer Python 3.10+; os adaptadores de destino suportam Python 3.10+ e Node.js 22+. Node suporta modos de benchmark/CPU; Python também suporta perfilamento de alocação.

Descubra e concorde sobre a carga de trabalho

Leia instruções do projeto, manifestos, lockfiles, pontos de entrada e testes existentes de desempenho/correção sem importar módulos do projeto ou executar hooks de configuração. Identifique linguagem, framework, interpretador, dependências e a operação lenta real. Selecione o adaptador Python ou Node e o tempo de execução existente do projeto. Para outra linguagem, explique o limite do coletor e proponha um profiler adequado, em vez de fingir que os adaptadores agrupados o suportam.

Escolha uma carga de trabalho representativa e limitada com um conjunto de dados estável, semente, concorrência, política de cache e saída esperada. Prefira um benchmark existente confiável ou um driver pequeno revisado que afirme o resultado. A coleta de teste e as importações do aplicativo também executam código. Se nenhuma carga de trabalho executável estiver disponível, entregue hipóteses e um plano de coleta; nunca invente medições.

Antes de executar um repositório desconhecido, mostre o interpretador exato, diretório de trabalho, comando e argumentos, número de invocações, timeout, caminhos de saída e possíveis efeitos de banco de dados/rede/arquivo. Obtenha autorização para essa carga de trabalho concreta se ainda não estiver coberta pela conversa. Permissão para inspecionar ou perfilar não é permissão para modificar o código do aplicativo. Pergunte antes de alterações, a menos que o usuário já tenha autorizado a otimização. Não pergunte novamente para um escopo inalterado já aprovado. Instalar dependências, anexar a processos e acessar produção exigem sua própria autorização aplicável.

O coletor executa código com as permissões do usuário: separação de subprocessos e timeouts não são uma sandbox de segurança. Use fixtures ou um banco de dados de teste quando necessário. Nunca passe credenciais em IDs de carga de trabalho ou argumentos de linha de comando; argumentos e caminhos são registrados localmente. Relatórios podem revelar caminhos internos. Não execute comandos desconhecidos apenas para descobrir o que eles fazem.

Colete evidências

Leia references/measurement.md para comandos, definições de métricas, decisões estatísticas e códigos de saída. O formato compartilhado versão 2 é definido em references/measurement.schema.json. Execute o coletor agrupado apenas para a carga de trabalho autorizada. Recolete artefatos antigos ou ad-hoc em vez de adivinhar seus limites de métricas ausentes.

• Primeiro, colete um benchmark não instrumentado. Salve todas as amostras, metadados de ambiente, identidade da carga de trabalho e revisão do código. Cada amostra usa um novo processo. Uma warmup descartada também é um novo processo; ela não aquece o estado do aplicativo em processos posteriores.
• Colete perfis de CPU e, para Python, perfis de alocação em invocações separadas. Seus tempos são diagnósticos e não podem ser substituídos pelos tempos do benchmark. O modo CPU Node retém um perfil V8 e diagnósticos de loop de eventos; hits de amostra não são contagens de chamadas e o perfil V8 inclui a inicialização do coletor. A coleta padrão de benchmark e alocação executa cada carga de trabalho oito vezes (uma warmup, sete execuções registradas); um perfil de CPU adiciona uma invocação sem warmup. Inclua essas contagens no plano aprovado.
• Preserve a linha de base antes de editar. Use novos nomes de saída: os scripts se recusam a sobrescrever artefatos. Escolha um diretório de resultados durável e mantenha cada JSON com seu diretório de artefatos adjacente. Registre a identidade do conjunto de dados, hashes de arquivo --input, semente, revisão, arquivos --source relevantes e política de cache. A semente registrada não sementeia o código do aplicativo; metadados automáticos não podem estabelecer o estado real do cache ou entradas não especificadas.
• Onde for significativo, use --expected-stdout com uma resposta conhecida revisada independentemente. Toda invocação, incluindo warmups, é verificada. Sem esse oráculo, a comparação automatizada deixa a correção não avaliada; execute e relate testes do projeto separadamente. A igualdade estreita de saída não cobre todos os invariantes do aplicativo.
• Prefira um driver finito para uma API Python ou worker. A ferramenta agrupada não é um gerador de carga HTTP, amostrador de processo ativo, profiler de CPU em todo o thread ou monitor de árvore de processos. Ela não mede diretamente bytes de E/S, contagens de consultas, percentis de solicitação ou throughput. Quando necessário, escolha instrumentação adicional com o usuário e registre seu escopo/overhead.

Diagnostique e proponha

Para cada descoberta, cite o artefato, função/arquivo/linha, contagem de chamadas ou tamanho de alocação e tempo próprio/acumulado relevante. Distinga fato observado, hipótese e mudança proposta. Tempos acumulados se sobrepõem na árvore de chamadas; nunca os some em uma porcentagem do tempo total. Tempo acumulado alto identifica um caminho caro, não necessariamente a função a ser reescrita.

Tempo de CPU abaixo do tempo de parede pode sugerir espera, mas não prova causalidade de disco, banco de dados ou rede. Uma chamada de função repetida não é prova de consultas N+1: obtenha contagens/spans de consulta e inspecione o loop. Snapshots de alocação descrevem alocações ativas no momento do snapshot, não todas as alocações transitórias ou um vazamento. Confirme vazamentos suspeitos com cargas de trabalho repetidas e evidências de retenção. Declare incógnitas explicitamente.

Priorize mudanças por contribuição medida, benefício provável, custo de implementação, risco de correção e tradeoffs de recursos. Descreva invalidação de cache, ordenação, transação, concorrência e efeitos de memória onde relevante. Não prometa uma melhoria percentual antes de medi-la.

Otimize e verifique dentro da autorização

Faça a menor alteração autorizada e preserve o trabalho não relacionado. Execute testes de correção relevantes e compare saídas/invariantes no mesmo fixture. Uma saída de processo bem-sucedida por si só não é verificação de correção.

Repita o mesmo benchmark e perfis afetados com o mesmo ambiente, carga de trabalho, semente, política de cache, contagem de execuções e timeout. rerun executa o código atual com a solicitação registrada e verifica hashes de entrada; não restaura uma revisão histórica. Compare tempo não instrumentado com tempo não instrumentado e métricas de memória comparáveis. O JSON comum não torna diferentes escopos de processo/thread ou intervalos de tempo de execução intercambiáveis. Se uma dependência/interpretador/carga de trabalho mudar, relate-o como um experimento separado em vez de ignorar verificações de incompatibilidade.

Use o comando de comparação agrupado para separar alterações descritivas de mediana/média, limites práticos configurados e evidências de permutação de amostras independentes sobre diferenças de médias (corrigidas por Holm entre as métricas comparadas). Selecione os limites antes de visualizar os resultados; o padrão de 5% não é universalmente significativo. Sobreposição de intervalo não é o teste de significância. O teste assume amostras independentes e trocáveis; inspecione a variabilidade e repita ou intercale medições A/B quando a deriva puder invalidar essa suposição. Resultados inconclusivos não estabelecem equivalência.

O status automatizado verified_improvement é limitado à carga de trabalho medida e oráculos de saída correspondentes aprovados, requer uma melhoria prática suportada na métrica primária e é bloqueado por regressões práticas suportadas em outras métricas comparadas. Verificações de saída com falha saem com código 3 e bloqueiam a verificação mesmo se a execução for mais rápida. --fail-on-regression faz com que regressões práticas suportadas saiam com código 1; uma saída zero para uma comparação inconclusiva não certifica melhoria. Não promova um resultado não avaliado ou com falha na narrativa. Execute cargas de trabalho vizinhas representativas se existirem e forem autorizadas. Reivindique cobertura de regressão apenas para cenários testados. Pare de expandir experimentos quando a pergunta acordada for respondida, uma execução falhar, os limites de autorização forem atingidos ou medições comparáveis não puderem ser obtidas.

Entregue o resultado

Use a linguagem do usuário. Cada coleta/comparação emite um relatório Markdown e JSON; adicione interpretação do agente na linguagem do usuário, retendo a evidência bruta. Lidere com o que foi encontrado, sua evidência e o próximo experimento, depois inclua:

• Escopo, comando, ambiente/revisões, entradas, contagem de repetições e limites de medição.
• Descobertas com evidências e confiança; separe sugestões não medidas.
• Mudanças feitas ou propostas, tradeoffs e verificações de correção com comandos/resultados.
• Medianas e médias antes/depois, min/max, contagem de amostras e porcentagens de mudança para cada métrica comparável. Testes e decisões práticas usam médias; mudanças na mediana são descritivas. Inclua unidades e limites de processo/thread/inicialização. Mudança positiva significa valores mais altos; negativa significa mais baixos. Marque linhas de base zero como indefinidas.
• Status: linha de base medida, inconclusivo, melhoria / regressão observada ou melhoria verificada. Reserve melhoria verificada para medições repetidas comparáveis mais verificações de correção aprovadas. Um ganho em velocidade com aumento de memória é um tradeoff, não uma vitória incondicional.
• Caminhos não testados, métricas indisponíveis, ruído, próxima ação e o comando de reexecução registrado concreto. Rotule claramente as demonstrações de resposta conhecida do scripts/demo.py agrupado e nunca reutilize seus números como resultados do aplicativo.

Arquivos Markdown/JSON são a linha de base portátil; um agente pode adicionar um gráfico usando suas ferramentas de apresentação disponíveis. Não dependa de um painel hospedado, endpoint de IA externo, conector proprietário ou ferramenta de gráfico opcional para concluir este fluxo de trabalho.