improve

# improve — audita con un modelo fuerte, ejecuta con modelos baratos `improve` es una habilidad de agente (formato Agent Skills) que audita cualquier codebase y escribe planes de implementación para que otros agentes los ejecuten. La premisa: gasta tu modelo más capaz en la parte donde la inteligencia se acumula — entender el codebase, juzgar qué vale la pena hacer, escribir la especificación — y deja la ejecución a modelos más baratos. La habilidad nunca implementa nada por sí misma; el plan es el producto. ``` tú → /improve (modelo caro, asesora) plans/ → 001-fix-n-plus-one.md (especificaciones autocontenidas) otro agente → implementa, prueba, publica (modelo barato, ejecuta) ``` ## Instalación ```bash npx skills add shadcn/improve ``` Funciona en cualquier agente que soporte el formato Agent Skills. Los planes son markdown plano, así que cualquier agente o humano puede retomarlos. ## Comandos - `/improve` — auditoría completa → hallazgos priorizados → planes - `/improve quick` — pasada barata: puntos críticos, solo los principales hallazgos - `/improve deep` — exhaustivo: cada paquete, cada categoría - `/improve security` — auditoría enfocada (también perf, tests, bugs, ...) - `/improve branch` — audita solo lo que cambia la rama actual - `/improve next` — sugerencias de funciones, hacia dónde llevar el proyecto - `/improve plan <descripción>` — omite la auditoría, especifica una cosa - `/improve review-plan <archivo>` — critica y ajusta un plan existente - `/improve execute <plan>` — despacha un ejecutor más barato, revisa su trabajo - `/improve reconcile` — actualiza el backlog: verifica, desbloquea, retira - `--issues` — también publica planes como issues de GitHub ## Primera ejecución típica 1. Abre tu agente en el repositorio y ejecuta `/improve` (o `/improve quick` para mantenerlo barato). 2. Mapea el repositorio, lo audita y devuelve una tabla de hallazgos. Responde con los que quieras planificar, p. ej. "plan 1, 3 y 5". 3. Los planes llegan a `plans/` — un archivo por cada uno, más un índice con el orden recomendado. Están pensados para ser revisados. 4. Entrega un plan a cualquier agente ("implementa plans/001-*.md"), o deja que la habilidad lo ejecute: `/improve execute 001` despacha un modelo más barato en un worktree aislado, revisa el diff contra el plan y reporta un veredicto. El merge sigue siendo tu decisión. 5. En la siguiente sesión, `/improve reconcile` limpia el backlog: verifica lo que se implementó, actualiza lo que se desvió, desbloquea lo que se atascó. Antes de un PR, `/improve branch` limita el mismo proceso a solo lo que cambia la rama. ## Cómo funciona - **Reconocimiento.** Mapea el repositorio: stack, convenciones y comandos exactos de build/test/lint, que se convierten en puertas de verificación en cada plan. También ingiere documentos de intención y diseño cuando existen — ADRs (`docs/adr/`), PRDs, `CONTEXT.md`, `DESIGN.md`, `PRODUCT.md` — para que los tradeoffs decididos no se vuelvan a señalar, las sugerencias de dirección se mantengan basadas en la intención declarada del producto, y los planes usen el propio vocabulario del repositorio. - **Auditoría.** Distribuye subagentes paralelos en nueve categorías: corrección, seguridad, rendimiento, cobertura de tests, deuda técnica, dependencias y migraciones, DX, documentación y dirección (las sugerencias de funciones deben citar evidencia del propio repositorio). Cada hallazgo lleva evidencia `archivo:línea`, impacto, esfuerzo y confianza. - **Evaluación.** Como los subagentes sobre-reportan, el asesor relee cada ubicación citada antes de mostrar nada; los falsos positivos se descartan, las atribuciones incorrectas se corrigen, los rechazos se registran. - **Priorización.** Los hallazgos llegan a una tabla ordenada por apalancamiento (impacto ÷ esfuerzo, ponderado por confianza). Tú eliges qué se convierte en planes. - **Planificación.** Un archivo por hallazgo seleccionado en `plans/`, con un índice, orden de prioridad y grafo de dependencias. ## Qué hace que los planes sean ejecutables Los planes apuntan al ejecutor más débil plausible — un modelo que nunca vio la sesión del asesor y que puede ser mucho más pequeño. Tres propiedades lo sostienen: - **Autocontenidos.** Todo el contexto está incluido: rutas de archivo exactas, extractos de código del estado actual, convenciones del repositorio con un archivo de ejemplo, comandos verificados. Sin "como se discutió arriba". - **Puertas de verificación.** Cada paso termina con un comando y su salida esperada; los criterios de finalización son comprobables por máquina, así el ejecutor nunca tiene que juzgar el éxito. - **Límites claros.** Listas explícitas de fuera de alcance y condiciones de STOP ("si X, detente y reporta") en lugar de dejar que un modelo pequeño improvise cuando la realidad no coincide con el plan. Cada plan sella el commit de git contra el que fue escrito, para que los ejecutores puedan hacer una verificación mecánica de desviación antes de tocar nada. ## Cerrando el ciclo - **`execute <plan>`** genera un subagente ejecutor más barato en un worktree de git aislado, le entrega el plan y luego revisa el resultado como un tech lead — re-ejecuta cada criterio de finalización, verifica el cumplimiento del alcance, lee el diff contra la intención. Veredicto: aprobar (el merge sigue siendo tu decisión), devolver para revisión (máximo 2 rondas), o bloquear y refinar el plan. - **`reconcile`** procesa lo que sucedió desde entonces: verifica que los planes DONE sigan vigentes, investiga los BLOCKED y los reescribe alrededor del obstáculo, actualiza los planes desviados, retira hallazgos arreglados de forma independiente. - **`--issues`** publica planes como issues de GitHub con el mismo cuerpo autocontenido, para que cualquier agente o humano pueda retomarlos donde ya vive el trabajo. ## Reglas estrictas - Nunca modifica el código fuente por sí mismo. Las únicas escrituras van a `plans/`; los ejecutores editan solo en worktrees desechables, y el merge siempre es tuyo. - Nunca ejecuta comandos que muten el árbol de trabajo — solo lectura, búsqueda y análisis de solo lectura. - Nunca reproduce valores secretos; solo ubicaciones y tipos de credenciales, siempre se recomienda rotación. - Si se le pide implementar, declina y señala el plan (u ofrece `execute`). ## Licencia MIT © shadcn