---
name: improve-system
description: El bucle de mejora del sistema (Austin Marchese), 5 modos — audit (revisa la base de conocimiento por info obsoleta), skill-review (mejora skills a partir del historial reciente), experience (incorpora la experiencia vivida de Vanessa), historical-review (rescata aprendizajes perdidos de sesiones recientes), foundation (revisa todo el montaje y entrevista por huecos). Úsalo cuando Vanessa diga "mejora el sistema", "haz un audit del knowledge", "revisa los skills", "qué hemos aprendido", "revisión del sistema", o al cerrar una sesión sustancial. Regla de oro: nunca arregles el mismo problema más de dos veces — a la segunda, va al sistema.
allowed-tools: Read, Edit, Write, Bash, Glob, Grep, WebFetch, WebSearch
metadata:
  category: Knowledge & Systems
  tags:
  - meta
  - self-improvement
  - cos
  - retrospective
---

# 🔁 improve-system — el bucle de mejora

Formaliza la pieza nº3 del sistema de los vídeos. Es el bucle que hace que el
sistema se vuelva más automático y a prueba de errores con cada uso.
**Regla de oro:** *nunca arregles el mismo problema más de dos veces* — a la
segunda, el arreglo va AL SISTEMA (a un `CLAUDE.md`, a un skill, o a la wiki),
no a la conversación.

Tiene **5 modos**. Si Vanessa no especifica, pregunta cuál (o sugiere el más
relevante al contexto). Cada modo produce cambios concretos + un resumen de qué
cambió y por qué, y se registra fechado en el log del proyecto (o en
`COS/HANDOFF.md` si es algo global del sistema).

## Modo 1 — `audit` (base de conocimiento)
Revisa el `knowledge/wiki/` (y `raw/`) del proyecto activo por:
- **Info obsoleta** (políticas que cambian, p.ej. Google; precios; APIs).
- **Contradicciones** entre digests.
- **Huecos** (fuentes en `raw/` sin digerir; temas sin fuente).
Acción: actualiza los digests, marca lo corregido, deja el `SCHEMA.md` al día.
- **Trazabilidad**: corre `python3 COS/check-traceability.py`; si marca archivos
  no registrados, añádelos a `COS/INDEX.md` (y a `REGISTRY.md` si es hook/automatización).

## Modo 2 — `skill-review` (+ selección de mecanismo)
Revisa los skills instalados (`~/.claude/skills/`) + el historial reciente de
uso. Para cada skill que se usó: ¿falló algo?, ¿se repitió una corrección?,
¿la `description` dispara cuando debe? Mejora el SKILL.md o crea uno nuevo si un
patrón se repite. (Aplica la regla de oro: un fallo visto 2 veces → al skill.)

**Selección de mecanismo (no solo skills):** al detectar un patrón mejorable,
recomienda PROACTIVAMENTE el mecanismo correcto — skill / agente / hook / loop /
automatización programada — según `COS/05_Automation_Systems/mechanism-decision-guide.md`.
Di cuál, por qué y el coste/beneficio; constrúyelo con el OK de Vanessa (ella no
se acuerda de pedirlo; es trabajo de Claude sugerirlo cuando mejore workflow/eficiencia).

## Modo 3 — `experience`
Incorpora la **experiencia vivida de Vanessa** — su mayor diferenciador. Entrevístala
brevemente (1 pregunta a la vez) sobre lo aprendido en la práctica (qué funcionó
con clientes, qué error real cometió, qué intuición resultó cierta) y guárdalo
donde corresponda: memoria (`~/.claude/.../memory/`), el `wiki/` del proyecto, o
el `CLAUDE.md`. Esto es lo que ningún competidor puede copiar.

## Modo 4 — `historical-review`
Revisa el arco COMPLETO de las sesiones recientes (logs `*_PROJECT_LOG.md`,
`HANDOFF.md`, transcripciones si están disponibles) — **no solo el último
problema** — con DOS lentes:
- **Reactiva** — errores, fricciones, correcciones repetidas y vueltas
  innecesarias; decisiones que no se registraron; patrones que deberían ser regla.
- **Proactiva (aunque NADA haya fallado)** — pasos manuales automatizables, cosas
  que Vanessa tuvo que pedir, fallos PREDECIBLES que autocorregir antes de que
  ocurran, verificaciones que deberían ser automáticas, momentos en que me anticipé
  a algo que ella debería haber previsto. El objetivo no es solo arreglar lo roto,
  sino dejar el sistema más automatizado que antes.

Destila **SOLO lo recurrente o de alto impacto** (lo que se repetirá en otras
sesiones/proyectos); ignora los one-off triviales. Enruta cada patrón a su alcance
(general → `Projects/CLAUDE.md`; stack-específico → `CLAUDE.md` del proyecto;
conocimiento → wiki). Cada instrucción añadida debe **PREVENIR** el fallo,
**DETECTARLO automáticamente antes de declarar algo "terminado"**, o **MEJORAR el
proceso de forma proactiva** (predecir, autocorregir, automatizar, anticipar) — con
el "porqué" en una línea, sin duplicar reglas existentes (intégralas/refínalas) ni
inflar los archivos. Es la versión sistemática de la retro de
`Projects/retro-prompt.md`.

## Modo 5 — `foundation`
Revisa **todo el montaje** (estructura de proyectos, skills, COS, memoria) y
**entrevista a Vanessa** por si falta algo respecto a sus objetivos: ¿el sistema
sirve a donde quiere ir el negocio?, ¿hay piezas de los vídeos sin implementar?,
¿algún proyecto quedó sin la estructura estándar? Produce una lista priorizada
con un único siguiente paso.

## Procedimiento general
1. Identifica el modo (pregunta si no está claro; sugiere según contexto).
2. Reúne EVIDENCIA primero (lee los archivos reales: wiki, logs, skills). Nada de
   teoría — el sistema mejora con hechos, igual que la disciplina de depuración.
3. Aplica los cambios concretos en los archivos del sistema.
4. Registra fechado en el log correspondiente.
5. Resume en lenguaje claro: qué patrón, qué instrucción añadiste, en qué archivo
   y por qué. **Si algo NO merece regla, dilo y por qué** — filtrar es parte del
   trabajo, no inflar el sistema con one-offs.

## Reglas
- Regla de oro arriba: a la 2ª vez, al sistema.
- No borres redundancia que funciona ni archivos; aumenta sin sobrescribir.
- Plain-language + di qué cuenta se usa cuando aplique.
- Herramientas gratis.

## Relación con otros skills
- **`ingest-source`** llena la biblioteca; `audit` la mantiene sana.
- Solapa con `Projects/retro-prompt.md` (retro de fin de sesión): `historical-review`
  es su versión recurrente y sistematizada.