Lente de Cuellos de Botella

¿Qué hace Lente de Cuellos de Botella?

Encuentra el cuello de botella. Demuestra la mejora.

Mantén la recolección local; no subas código fuente, trazas o informes por defecto. Las instrucciones portátiles y los scripts incluidos no requieren un proveedor de agente en particular. Resuelve las rutas incluidas relativas a este SKILL.md. La CLI requiere Python 3.10+; los adaptadores objetivo soportan Python 3.10+ y Node.js 22+. Node soporta modos de benchmark/CPU; Python también soporta perfilado de asignación.

Descubrir y acordar la carga de trabajo

Lee las instrucciones del proyecto, manifiestos, archivos de bloqueo, puntos de entrada y pruebas de rendimiento/corrección existentes sin importar módulos del proyecto ni ejecutar hooks de configuración. Identifica el lenguaje, framework, intérprete, dependencias y la operación lenta real. Selecciona el adaptador Python o Node y el tiempo de ejecución del proyecto existente. Para otro lenguaje, explica el límite del recopilador y propón un perfilador adecuado en lugar de pretender que los adaptadores incluidos lo soportan.

Elige una carga de trabajo representativa y acotada con un conjunto de datos estable, semilla, concurrencia, política de caché y salida esperada. Prefiere un benchmark existente de confianza o un pequeño controlador revisado que afirme el resultado. La recolección de pruebas y las importaciones de la aplicación también ejecutan código. Si no hay una carga de trabajo ejecutable disponible, entrega hipótesis y un plan de recolección; nunca inventes mediciones.

Antes de ejecutar un repositorio desconocido, muestra el intérprete exacto, directorio de trabajo, comando y argumentos, número de invocaciones, tiempo de espera, rutas de salida y posibles efectos en base de datos/red/archivos. Obtén autorización para esa carga de trabajo concreta si no está cubierta por la conversación. El permiso para inspeccionar o perfilar no es permiso para modificar el código de la aplicación. Pregunta antes de hacer cambios a menos que el usuario ya haya autorizado la optimización. No preguntes de nuevo por un ámbito ya aprobado y sin cambios. La instalación de dependencias, la conexión a procesos y el acceso a producción requieren su propia autorización aplicable.

El recopilador ejecuta código con los permisos del usuario: la separación en subprocesos y los tiempos de espera no son un entorno aislado de seguridad. Usa fixtures o una base de datos de prueba cuando sea necesario. Nunca pases credenciales en IDs de carga de trabajo o argumentos de línea de comandos; los argumentos y rutas se registran localmente. Los informes pueden revelar rutas internas. No ejecutes comandos desconocidos solo para descubrir qué hacen.

Recopilar evidencia

Lee references/measurement.md para comandos, definiciones de métricas, decisiones estadísticas y códigos de salida. El formato compartido versión 2 se define en references/measurement.schema.json. Ejecuta el recopilador incluido solo para la carga de trabajo autorizada. Vuelve a recopilar artefactos antiguos o ad-hoc en lugar de adivinar sus límites de métricas faltantes.

• Primero recopila un benchmark sin instrumentación. Guarda todas las muestras, metadatos del entorno, identidad de la carga de trabajo y revisión del código. Cada muestra usa un nuevo proceso. Un warmup descartado también es un nuevo proceso; no calienta el estado de la aplicación en procesos posteriores.
• Recopila perfiles de CPU y, para Python, perfiles de asignación en invocaciones separadas. Sus tiempos son de diagnóstico y no pueden sustituir los tiempos del benchmark. El modo CPU de Node retiene un perfil V8 y diagnóstico del bucle de eventos; los hits de muestra no son conteos de llamadas y el perfil V8 incluye el inicio del recopilador. La recolección por defecto de benchmark y asignación ejecuta la carga de trabajo ocho veces (un warmup, siete ejecuciones registradas); un perfil de CPU añade una invocación sin warmup. Incluye estos conteos en el plan aprobado.
• Conserva la línea base antes de editar. Usa nombres de salida nuevos: los scripts se niegan a sobrescribir artefactos. Elige un directorio de resultados duradero y guarda cada JSON con su directorio de artefactos adyacente. Registra la identidad del conjunto de datos, hashes de archivos --input, semilla, revisión, archivos --source relevantes y política de caché. La semilla registrada no siembra el código de la aplicación; los metadatos automáticos no pueden establecer el estado real de la caché ni las entradas no especificadas.
• Cuando sea significativo, usa --expected-stdout con una respuesta conocida revisada independientemente. Cada invocación, incluidos los warmups, se verifica. Sin ese oráculo, la comparación automatizada deja la corrección sin evaluar; ejecuta y reporta las pruebas del proyecto por separado. La igualdad estrecha de la salida no cubre todos los invariantes de la aplicación.
• Prefiere un controlador finito para una API de Python o worker. La herramienta incluida no es un generador de carga HTTP, muestreador de procesos en vivo, perfilador de CPU a nivel de hilo o monitor de árbol de procesos. No mide directamente bytes de E/S, conteos de consultas, percentiles de solicitudes o rendimiento. Cuando sea necesario, elige instrumentación adicional con el usuario y registra su alcance/overhead.

Diagnosticar y proponer

Para cada hallazgo, cita el artefacto, función/archivo/línea, conteo de llamadas o tamaño de asignación, y tiempo propio/acumulado relevante. Distingue hecho observado, hipótesis y cambio propuesto. Los tiempos acumulados se superponen en el árbol de llamadas; nunca los sumes en un porcentaje del tiempo total. Un tiempo acumulado alto identifica una ruta costosa, no necesariamente la función a reescribir.

Un tiempo de CPU por debajo del tiempo de pared puede sugerir espera, pero no prueba causalidad de disco, base de datos o red. Una llamada a función repetida no es prueba de consultas N+1: obtén conteos/intervalos de consultas e inspecciona el bucle. Las instantáneas de asignación describen asignaciones vivas en el momento de la instantánea, no todas las asignaciones transitorias o una fuga. Confirma las fugas sospechosas con cargas de trabajo repetidas y evidencia de retención. Declara explícitamente las incógnitas.

Prioriza los cambios por contribución medida, beneficio probable, costo de implementación, riesgo de corrección y compensaciones de recursos. Describe efectos de invalidación de caché, ordenamiento, transacciones, concurrencia y memoria cuando sea relevante. No prometas un porcentaje de mejora antes de medirlo.

Optimizar y verificar dentro de la autorización

Haz el cambio autorizado más pequeño y conserva el trabajo no relacionado. Ejecuta las pruebas de corrección relevantes y compara salidas/invariantes en el mismo fixture. Una salida exitosa del proceso por sí sola no es verificación de corrección.

Repite el mismo benchmark y perfiles afectados con el mismo entorno, carga de trabajo, semilla, política de caché, número de ejecuciones y tiempo de espera. rerun ejecuta el código actual con la solicitud registrada y verifica los hashes de entrada; no restaura una revisión histórica. Compara tiempos sin instrumentación con tiempos sin instrumentación, y métricas de memoria similares. El JSON común no hace intercambiables diferentes ámbitos de proceso/hilo o intervalos de tiempo de ejecución. Si una dependencia/intérprete/carga de trabajo cambia, repórtalo como un experimento separado en lugar de evitar las comprobaciones de incompatibilidad.

Usa el comando de comparación incluido para separar cambios descriptivos de mediana/media, umbrales prácticos configurados y evidencia de prueba de permutación de muestras independientes sobre diferencias de medias (corregida Holm entre métricas comparadas). Selecciona los umbrales antes de ver los resultados; el 5% por defecto no es universalmente significativo. La superposición de rangos no es la prueba de significancia. La prueba asume muestras independientes e intercambiables; inspecciona la variabilidad y repite o intercala mediciones A/B cuando la deriva podría invalidar esa suposición. Los resultados no concluyentes no establecen equivalencia.

El estado automático verified_improvement se limita a la carga de trabajo medida y la correspondencia con oráculos de salida exitosos, requiere una mejora práctica de métrica primaria compatible, y está bloqueado por regresiones prácticas compatibles en otras métricas comparadas. Las comprobaciones de salida fallidas salen con código 3 y bloquean la verificación incluso si la ejecución es más rápida. --fail-on-regression hace que las regresiones prácticas compatibles salgan con código 1; una salida cero para una comparación no concluyente no certifica una mejora. No promuevas un resultado no evaluado o fallido en la narrativa. Ejecuta cargas de trabajo vecinas representativas si existen y están autorizadas. Reclama cobertura de regresión solo para escenarios probados. Deja de expandir experimentos cuando la pregunta acordada esté respondida, una ejecución falle, se alcancen los límites de autorización o no se puedan obtener mediciones comparables.

Entregar el resultado

Usa el lenguaje del usuario. Cada recolección/comparación emite un informe Markdown y JSON; añade la interpretación del agente en el lenguaje del usuario mientras conservas la evidencia bruta. Comienza con lo que se encontró, su evidencia y el siguiente experimento, luego incluye:

• Alcance, comando, entorno/revisiones, entradas, número de repeticiones y límites de medición.
• Hallazgos con evidencia y confianza; separa las sugerencias no medidas.
• Cambios realizados o propuestos, compensaciones y comprobaciones de corrección con comandos/resultados.
• Medianas y medias antes/después, mínimo/máximo, número de muestras y porcentajes de cambio para cada métrica comparable. Las pruebas y decisiones prácticas usan medias; los cambios de mediana son descriptivos. Incluye unidades y límites de proceso/hilo/inicio. Cambio positivo significa valores más altos; negativo significa más bajos. Marca las líneas base cero como indefinidas.
• Estado: línea base medida, no concluyente, mejora / regresión observada o mejora verificada. Reserva mejora verificada para mediciones repetidas comparables más comprobaciones de corrección exitosas. Una ganancia en velocidad con mayor memoria es una compensación, no una victoria incondicional.
• Rutas no probadas, métricas no disponibles, ruido, siguiente acción y el comando concreto de re-ejecución registrado. Etiqueta claramente las demostraciones de respuesta conocida del scripts/demo.py incluido y nunca reutilices sus números como resultados de la aplicación.

Los archivos Markdown/JSON son la línea base portátil; un agente puede agregar un gráfico usando sus herramientas de presentación disponibles. No dependas de un panel alojado, un endpoint de IA externo, un conector propietario o una herramienta de gráficos opcional para completar este flujo de trabajo.