Communitygithub.com

Yingqi-Han/learning-retrospective-skill

Habilidad agnóstica de agente para romper bucles de reintentos y capturar lecciones verificadas del flujo de trabajo.

¿Qué es learning-retrospective-skill?

Esta habilidad está diseñada para evitar que los agentes de IA (como Claude Code, Cursor o Codex) repitan errores al capturar lecciones verificadas y almacenarlas en la memoria o documentación del proyecto. Distingue entre problemas conocidos (donde ya existe una lección almacenada) y problemas novedosos (donde se debe explorar sin interrupción hasta resolverlo, y luego capturar la lección). La habilidad se activa automáticamente ante señales como fallos repetidos del mismo comando, cambios de herramienta sin hipótesis nueva, o cuando el usuario indica que el agente está en un bucle. Su flujo de trabajo incluye pausar el bucle, clasificar el problema, elegir una hipótesis, completar la tarea, capturar la lección (con comandos exactos, rutas y errores) y almacenarla en la superficie adecuada (memoria del usuario o documentación del repositorio) tras pasar una puerta de permisos de escritura. También incluye un mecanismo de activación automática mediante hooks en plataformas compatibles.

Compatible con✓Claude Code✓Codex CLI~Cursor
npx skills add Yingqi-Han/learning-retrospective-skill

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Retrospectiva de Aprendizaje

Usa esta habilidad para convertir lecciones verificadas en contexto duradero para agentes futuros, de modo que un problema resuelto una vez nunca se vuelva a resolver por prueba y error. Mantén la tarea principal en movimiento; la retrospectiva debe ser un bucle de control corto, no un nuevo proyecto.

El fallo no es error. Los intentos repetidos en un problema novedoso son exploración legítima y no deben suprimirse; la única disciplina que necesita un problema novedoso es no reintentar al pie de la letra y una hipótesis explícita por intento. El comportamiento que esta habilidad existe para eliminar es diferente: luchar con el mismo problema por segunda vez porque la primera solución nunca se capturó, o se capturó pero no se recordó. Por lo tanto, la habilidad tiene dos modos con diferentes fortalezas:

  • Problema conocido (una lección o memoria almacenada cubre esta firma de fallo): intervenir temprano: recordar la lección antes del siguiente intento y seguirla.
  • Problema novedoso (sin lección previa): no interrumpir la exploración. Variar el enfoque en lugar de reintentar al pie de la letra, resolverlo y luego capturar la lección.

Captura Posterior a la Resolución

Este es el modo automático principal. Después de que una tarea tenga éxito, verifica una pregunta antes de finalizar el turno: ¿llegar hasta aquí implicó dos o más intentos fallidos, una solución no obvia, un hecho específico de la máquina, o un orden de operaciones que un agente futuro tendría que redescubrir? Si es así, ejecuta los pasos 5-6 del Flujo de Trabajo (capturar la lección, almacenarla en la superficie correcta, sujeto a la Puerta de Permisos de Escritura). Si no, termina normalmente: no fabriques lecciones a partir de trabajo rutinario.

La captura debe ocurrir mientras la evidencia aún está en contexto: comandos exactos, texto de error exacto, qué se intentó y por qué falló. Una lección escrita desde el recuerdo de la lucha vale menos que una escrita desde la transcripción de la misma.

Señales de Bucle

Activa una retrospectiva cuando aparezca una o más señales:

  • El mismo comando, prueba, conversión, instalación, llamada a la API o acción de UI falla dos veces.
  • El agente comienza un descubrimiento amplio después de que un hecho local verificado debería haberse comprobado.
  • El agente cambia de herramientas repetidamente sin una nueva hipótesis.
  • El usuario dice que el agente está en bucle, olvidó trabajo previo, o debería recordar la lección.
  • Una corrección depende de rutas específicas de la máquina, variables de entorno, herramientas instaladas, flujo de credenciales, estado de la cuenta, o convenciones del proyecto.
  • Un fallo se resolvió mediante un comando no obvio, solución local, o orden de operaciones.

No ejecutes este flujo de trabajo para cada error pequeño. Úsalo cuando la lección sea reutilizable o el comportamiento actual esté empezando a perder tiempo.

No Activadores

No invoques esta habilidad para:

  • Un error común por primera vez con una corrección obvia siguiente.
  • Depuración normal donde cada intento produce nueva evidencia.
  • Tareas de mera explicación, resumen, traducción o escritura.
  • Revisión amplia del proyecto a menos que ya haya aparecido un patrón de fallo repetido.
  • Actualizaciones de memoria solicitadas por el usuario que no impliquen una lección del flujo de trabajo.

Puerta de Permisos de Escritura

Antes de escribir en la memoria del usuario, documentación del repositorio, reglas del proyecto o de otra habilidad:

  • Si el usuario solicitó explícitamente guardar, actualizar o escribir la lección, procede.
  • De lo contrario, presenta la lección propuesta y la superficie de destino primero.
  • Nunca modifiques las instrucciones del proyecto, habilidades o memoria persistente de forma silenciosa.
  • Nunca almacenes secretos, tokens, credenciales, cookies, datos privados o registros largos sin procesar.

Flujo de Trabajo

  1. Pausa el bucle.

    • Detén los reintentos al pie de la letra, la búsqueda amplia sin enfoque y las ediciones especulativas.
    • Indica el objetivo inmediato, la última acción fallida y el error o síntoma exacto.
    • Preserva cualquier proceso en ejecución o datos del usuario antes de cambiar de rumbo.
  2. Reconstruye la evidencia y clasifica el problema.

    • Busca primero en la memoria existente y la guía del proyecto esta firma de fallo. Si una lección anterior lo cubre, esto es un problema conocido: sigue la lección en lugar de re-derivarla.
    • Si nada lo cubre, esto es un problema novedoso: continúa explorando con hipótesis variadas y planea capturar la lección después de la resolución.
    • Enumera lo que ya está verificado, incluyendo rutas, versiones, comandos, salidas y archivos.
    • Prefiere verificación económica de hechos propensos a desviarse sobre suposiciones.
  3. Elige una siguiente hipótesis.

    • Elige el comando o edición más pequeño que pruebe directamente la hipótesis principal.
    • Agrega una puerta de fallo: define qué resultado significa éxito, qué resultado significa detenerse y qué plan de contingencia está permitido.
    • Evita caer en descubrimientos de contingencia no relacionados cuando la puerta falle.
  4. Completa la tarea del usuario primero.

    • Arregla, convierte, instala, prueba o configura el objetivo real.
    • Verifica con evidencia observada, no con confianza.
    • Mantén copias de seguridad temporales y elimínalas después de que el usuario confirme que ya no son necesarias.
  5. Captura la lección.

    • Registra solo lecciones que sean verificadas, reutilizables y no obvias.
    • Incluye comandos exactos, rutas, versiones, texto de fallo y el mejor orden de operaciones.
    • Excluye secretos, datos privados, registros largos y suposiciones no verificadas.
    • Prefiere una pequeña actualización de memoria sobre una narrativa grande.
  6. Almacénala en la superficie correcta.

    • Pasa la Puerta de Permisos de Escritura antes de hacer ediciones persistentes.
    • Usa memoria a nivel de usuario para hechos de máquina o preferencias entre proyectos.
    • Usa documentos del repositorio/proyecto para convenciones específicas del proyecto.
    • Actualiza una habilidad existente solo cuando la lección cambie un procedimiento reutilizable.
    • Crea una nueva habilidad solo cuando el procedimiento sea recurrente, portátil y valga la pena activarlo automáticamente.
    • Consulta references/memory-surfaces.md para obtener orientación de colocación neutral a la plataforma.
  7. Opcionalmente, pide a un revisor independiente.

    • Usa cualquier agente secundario, modelo, prompt de revisor o sesión nueva disponible; no requieras un proveedor o modelo específico.
    • Dale solo las rutas de los artefactos, el resumen del bucle fallido y las preguntas de validación concretas.
    • Pide la mejora más pequeña en seguridad o claridad.
    • Si no existe un subagente, ejecuta tú mismo la misma lista de verificación.
    • Consulta references/reviewer-prompt.md.

Activación Automática

Esta habilidad normalmente se recuerda a través de su descripción, que es más débil exactamente cuando un agente está en medio de un bucle. Si tu plataforma soporta hooks o devoluciones de llamada de eventos de herramientas, conecta un detector de fallos repetidos que inyecte un recordatorio para invocar esta habilidad. Los scripts de detector ejecutables viven en hooks/ (variantes de Claude Code y Codex) con un conjunto de pruebas automatizadas en tests/; consulta references/hook-activation.md para registro, requisitos de confianza y el patrón general para otras plataformas. Trata cualquier configuración de hook que escribas como un artefacto bajo las reglas de esta habilidad: ejecuta el conjunto de pruebas, luego fuerza un fallo real para probar que se activa, antes de confiar en él.

Ejemplos

Usa los ejemplos como anclas para el comportamiento de activación y ejecución:

  • examples/pdf-rendering-loop.md
  • examples/github-actions-loop.md
  • examples/docx-conversion-loop.md
  • examples/zotero-linked-attachment-loop.md
  • examples/dependency-install-loop.md
  • examples/filled-lesson-libreoffice.md (una lección completada, no un patrón)
  • examples/bad-lessons.md (contra-ejemplos: capturas que envenenan la memoria)

Plantilla de Lección

# Lección: <nombre corto>

## Activador
- ¿Qué patrón debería hacer que un agente futuro recuerde esto?

## Hechos Verificados
- Rutas, versiones, comandos, archivos o estado de cuenta exactos.

## Intentos Fallidos a Evitar
- Intentos que se probaron y por qué fueron incorrectos o derrochadores.

## Procedimiento Preferido
1. Primer comando/verificación.
2. Puerta de validación.
3. Plan de contingencia solo si la puerta falla.

## Evidencia de Validación
- El comando exacto y la salida observada que demostraron que el procedimiento preferido funciona.

## Riesgo de Desviación
- Lo que puede invalidar esta lección: versión, ruta, forma de la API, estado de cuenta, SO, permisos.

## Última Verificación
- AAAA-MM-DD

## Alcance
- Aplica a: <máquina/proyecto/herramienta/contexto>
- No aplica a: <límites conocidos>

Respuesta Final

Informa al usuario:

  • Qué bucle se detectó.
  • Qué resultado de tarea se logró.
  • Qué lección se capturó y dónde se escribió.
  • Qué limitación persiste, especialmente si los agentes futuros deben cargar explícitamente la memoria o invocar la habilidad.

Skills relacionados