harness-retro

Harness retro

Encuentra dónde salieron mal las sesiones pasadas y cambia la configuración para que no vuelva a suceder. Cada hallazgo debe apuntar a evidencia en una transcripción. Nunca apliques un cambio antes de que el usuario lo apruebe.

1. Extraer las transcripciones

El extractor es un script solo con la biblioteca estándar que se encuentra junto a este archivo. Ejecútalo con -I. Escribe su salida en el bloc de notas de la sesión, o en un directorio temporal si no existe:

python3 -I <directorio base de este skill>/scripts/mine.py [RUTA] [--since 30d] --out <bloc>/retro.json

• Sin RUTA, extrae el proyecto del directorio de trabajo actual. Para extraer un proyecto diferente, proporciona la ruta de su directorio de trabajo, o usa --project=<clave> con el nombre de la carpeta dentro de ~/.claude/projects. Usa la forma =, porque las claves comienzan con -.
• Usa --since si el usuario ha nombrado una ventana de tiempo. Aumenta --max-bytes (por defecto 40000) solo si la salida está truncada y necesitas más.
• Si el usuario pregunta sobre todos los proyectos, ejecútalo una vez por cada carpeta en ~/.claude/projects y examina los proyectos con mayor fricción.

El script imprime un resumen de una línea. Si ha escaneado pocas o ninguna sesión, informa al usuario. Claude Code elimina las transcripciones después de cleanupPeriodDays (por defecto 30), por lo que el historial más antiguo puede haber desaparecido. Sugiere aumentar esa configuración si quieren retrospectivas más profundas en el futuro.

2. Leer los aciertos

El JSON lista las sesiones ordenadas por puntuación de fricción. Cada acierto tiene signal, score, ts, prior_prompt (lo que preguntó el usuario), recent_actions (las últimas llamadas a herramientas de Claude antes del acierto), y user_reaction o detail.

Señales, aproximadamente en orden de valor:

• user_correction: el usuario se opuso. Puntuaciones de 5 o más indican fuerte frustración o una repetición ("todavía", "otra vez", "te dije", insultos).
• edit_revert y edit_churn: Claude fue y vino en el mismo archivo.
• tool_error_streak: Claude seguía encontrando el mismo fallo.
• interrupted: el usuario detuvo a Claude a mitad de turno. Esto suele significar que iba en la dirección equivocada.
• permission_denied: Claude intentó algo que el usuario o el clasificador bloquearon.
• self_retraction: Claude admitió un error. Esta señal es ruidosa, así que úsala solo como evidencia de apoyo.

Las expresiones regulares son rudimentarias. Descarta los falsos positivos, como "no" en una instrucción normal o "inténtalo de nuevo" después de un error de red. Cuando un acierto sea ambiguo, abre la transcripción alrededor de él. El archivo es ~/.claude/projects/<clave>/<sesión>.jsonl; busca la marca de tiempo y lee unas pocas líneas a cada lado. No leas transcripciones enteras.

3. Agrupar en patrones

Agrupa los aciertos reales en patrones recurrentes. Un patrón es una causa raíz, escrita como algo que Claude hace mal. Ejemplos: "Genera nuevas imágenes en lugar de usar la biblioteca de activos aprobada", "Edita la versión actual en lugar de crear una nueva", "Afirma que un cambio es visible sin verificar la salida construida". Para cada patrón, registra:

• Con qué frecuencia ocurrió y en cuántas sesiones.
• Dos o tres citas cortas del usuario, con el título de la sesión y la fecha.
• La causa raíz. Elige una: conocimiento faltante, una regla que existía pero fue ignorada, un flujo de trabajo por defecto incorrecto, verificación faltante, o una brecha de herramienta o permiso.

Un solo incidente cuenta solo si el usuario estaba claramente enojado o el costo fue alto, por ejemplo trabajo destructivo o perdido.

4. Verificar el harness actual

Antes de proponer nada, lee lo que ya está en su lugar:

• ~/.claude/CLAUDE.md, además del CLAUDE.md del proyecto y cualquier anidado.
• ~/.claude/settings.json, y los archivos .claude/settings.json y .claude/settings.local.json del proyecto (hooks, permisos).
• El directorio de memoria del proyecto ~/.claude/projects/<clave>/memory/ y su MEMORY.md.
• Skills en ~/.claude/skills/ y los del proyecto en .claude/skills/.

Si un patrón ya está cubierto por una regla que Claude ignoró, añadir la misma regla de nuevo no ayudará. Haz la regla más específica y colócala donde será vista, o muévete a un mecanismo más fuerte.

5. Elegir la corrección

Para cada patrón, usa el mecanismo más ligero que realmente funcione:

Causa raíz	Corrección
Un hecho del proyecto que Claude no sabía	Un archivo de memoria en el directorio de memoria del proyecto, con frontmatter name, description, metadata.type, un cuerpo con Por qué: y Cómo aplicar:, y un puntero de una línea en MEMORY.md. Actualiza una memoria existente en lugar de duplicarla.
Una regla permanente para este repositorio	CLAUDE.md del proyecto
Una regla para todos los proyectos	~/.claude/CLAUDE.md
Una regla que sigue siendo incumplida y puede verificarse con un script (formateo, cadenas prohibidas, un comando requerido antes de confirmar)	Un hook en settings.json. Usa el skill update-config si está disponible.
Solicitudes o denegaciones de permiso repetidas para comandos seguros	Propón entradas en la lista blanca, o sugiere el skill fewer-permission-prompts si está disponible. No amplíes los permisos para comandos destructivos.
Un flujo de trabajo de varios pasos que sigue fallando	Un skill nuevo o editado (usa skill-creator si está disponible).
Un error del producto Claude Code	Anótalo en el informe. No hay corrección en el harness.

Escribe las reglas como instrucciones concretas y verificables que nombren la cosa específica, como archivos, rutas de activos, comandos o nombres de versiones. "Ten cuidado con las imágenes" es demasiado vago para actuar.

6. Informar y obtener aprobación

Presenta una sección por patrón, primero el más costoso. Cada sección proporciona:

1. El patrón, en una línea.
2. La evidencia: recuento, sesiones y 2 o 3 citas cortas con fecha.
3. La causa raíz.
4. El cambio propuesto: el archivo de destino y el texto exacto o diff.

Luego pregunta qué cambios aplicar. Una AskUserQuestion de selección múltiple con una opción por patrón funciona bien. Aplica solo los cambios aprobados, luego lista qué cambió y dónde.

Escribir reglas

Todo lo que se escriba en CLAUDE.md, memoria o skills debe seguir las reglas de escritura en los propios archivos CLAUDE.md del usuario, como tono, palabras prohibidas o reglas de atribución. Mantenlo breve y específico. Las citas de las transcripciones pueden incluir secretos que el usuario haya pegado. El extractor redacta formatos de clave comunes, pero verifica antes de copiar texto en cualquier archivo.