gonzalezpazmonica/code-improvement-loop

Skill: Code Improvement Loop

Regla de seguridad: @docs/rules/domain/autonomous-safety.md — NUNCA merge, SIEMPRE PR Draft con reviewer humano. Inspirado en: autoresearch — patrón modificar → medir → mantener/descartar.

Cuándo usar esta skill

• Se quiere mejorar la calidad del código de forma continua y medible
• Hay deuda técnica acumulada (baja cobertura, alta complejidad, warnings de linter, TODOs pendientes)
• Se busca generar mejoras incrementales con métricas antes/después para revisión humana

Qué produce

1. PRs en Draft — uno por mejora que supere las métricas baseline, asignados a AUTONOMOUS_REVIEWER
2. improvement-results.tsv — output/improvement-results-{YYYYMMDD}.tsv
3. Informe de oportunidades — output/improvement-opportunities-{YYYYMMDD}.md
4. Audit log — output/agent-runs/improvement-{YYYYMMDD}-audit.log

Prerequisitos

1. AUTONOMOUS_REVIEWER configurado            → si no: ❌ ABORT
2. Tests pasan (baseline sano)                → si no: ❌ ABORT
3. Métricas baseline capturadas               → si no: capturar antes de empezar
4. Auto Mode activado (claude --enable-auto-mode) → si no: ⚠️ warning, continuar

Auto Mode: activar claude --enable-auto-mode en la sesión que invoque esta skill — añade classifier pre-tool-call complementario a autonomous-safety.md.

Flujo completo (patrón autoresearch adaptado)

Humano ejecuta /code-improve [--scope {path}] [--tipo {coverage|complexity|lint|deps|todos}]
    ↓
Validar prerequisitos
    ↓
Capturar métricas baseline:
  - Cobertura de tests (%)
  - Complejidad ciclomática (promedio y max)
  - Warnings de linter (count)
  - TODOs sin ticket (count)
  - Dependencias desactualizadas (count)
    ↓
Detectar oportunidades de mejora → mostrar lista → PEDIR CONFIRMACIÓN
    ↓
[Humano confirma]
    ↓
LOOP (por cada oportunidad, hasta max_tasks o max_failures):
  ↓
  Crear rama: agent/improve-{tipo}-{id}
  ↓
  Crear worktree aislado
  ↓
  Aplicar mejora (time-box: AGENT_TASK_TIMEOUT_MINUTES)
  ↓
  Ejecutar tests + capturar métricas post-cambio
  ↓
  Comparar métricas:
    ¿Tests siguen pasando?
    ¿Métrica objetivo mejoró?
    ¿Ninguna otra métrica degradó significativamente?
      ↓
    TODO SÍ → Crear PR Draft con:
      - Título: "agent(improve): {descripción}"
      - Body: métricas antes/después, ficheros modificados, riesgo estimado
      - Reviewer: AUTONOMOUS_REVIEWER
      - Registrar como "pr-created" en results.tsv
      ↓
    ALGO NO → Descartar rama (git branch -D) → registrar como "discarded"
  ↓
  Siguiente oportunidad
    ↓
Generar informe resumen con todas las mejoras propuestas

Tipos de mejora detectables

1. Cobertura de tests (--tipo coverage)

• Identifica ficheros con cobertura < TEST_COVERAGE_MIN_PERCENT
• Genera tests unitarios para cubrir ramas no cubiertas
• Métrica: delta de cobertura (%)

2. Complejidad ciclomática (--tipo complexity)

• Identifica funciones con complejidad > 10
• Aplica refactoring: extract method, simplify conditions, early return
• Métrica: complejidad promedio y máxima

3. Warnings de linter (--tipo lint)

• Ejecuta linter del proyecto y recopila warnings
• Corrige automáticamente los que tienen fix seguro
• Métrica: count de warnings

4. Dependencias (--tipo deps)

• Identifica dependencias con updates menores/patch disponibles
• Aplica update + ejecuta tests
• Métrica: count de dependencias desactualizadas

5. TODOs pendientes (--tipo todos)

• Identifica TODOs en código que refieren a tickets cerrados
• Resuelve el TODO o lo elimina si ya está resuelto
• Métrica: count de TODOs

Formato de results.tsv

timestamp	tipo	fichero	rama	status	metrica_antes	metrica_despues	delta	pr_url	descripcion
2026-03-12T02:00:00	coverage	src/auth/	agent/improve-coverage-auth	pr-created	62.3%	78.1%	+15.8%	https://...	Add tests for login flow
2026-03-12T02:18:00	complexity	src/api/handler.ts	agent/improve-complexity-handler	pr-created	14.2	8.7	-5.5	https://...	Extract methods from handler
2026-03-12T02:35:00	lint	src/	agent/improve-lint-warnings	discarded	23	25	+2	-	Fix introduced new warnings

Restricciones estrictas

NUNCA → Hacer merge de un PR
NUNCA → Aprobar un PR
NUNCA → Hacer commit en rama de humano
NUNCA → Cambiar la API pública de un módulo
NUNCA → Modificar tests existentes (solo AÑADIR nuevos)
NUNCA → Aplicar mejoras que degraden CUALQUIER métrica
SIEMPRE → PR en Draft con AUTONOMOUS_REVIEWER
SIEMPRE → Métricas antes/después en el body del PR
SIEMPRE → Ramas agent/improve-*
SIEMPRE → Un PR por mejora (atómico, fácil de revisar)

Cuándo NO usar

• Para refactorings mayores que cambian arquitectura
• Para actualizar dependencias major (breaking changes)
• Si los tests del proyecto no pasan
• Para mejoras que requieren decisiones de diseño humanas