Debrief

¿Qué hace Debrief?

Un debrief es el instrumento de un meta-objetivo permanente: un proceso que mejora nuestros procesos. Analiza cómo la persona y el agente trabajaron juntos, con evidencia, y convierte lo que encuentra en tres tipos de resultado: lecciones para el agente (instrucciones, skills, workflows, hooks), lecciones para la persona (cómo liderar mejor al agente) y cambios en la configuración del proyecto. Es honesto en ambas direcciones y nunca fabrica críticas: una sesión que fue bien recibe un informe breve.

Estructura y reglas adaptadas de dos habilidades con licencia MIT, con agradecimientos: debrief de Wavez (los cuatro grupos de verificación, "cada hallazgo cita un momento", nada se aplica sin aprobación) y retrospective de florianbuetow (informes guardados como historial, recomendaciones anteriores verificadas y problemas recurrentes escalados, causa raíz y sugerencia por hallazgo). La sección de coaching, el hábito de los cinco porqués y el script de uso son propios de esta habilidad.

Entradas

1. La conversación. La fuente principal: llamadas a herramientas, preguntas y cuándo se hicieron, correcciones y confirmaciones por parte del usuario, informes de subagentes, errores y reintentos. Si la sesión se compactó, indícalo en el informe y trata el resumen como evidencia de baja confianza; no inventes momentos para la parte que no puedes ver.

2. Los números. Ejecuta el script incluido para el uso de la sesión: turnos, llamadas a herramientas por nombre, subagentes y workflows con sus tokens, modelos utilizados, tokens de salida por modelo, duración, compactaciones. Lee la transcripción de la sesión en ~/.claude/projects/<slug-del-proyecto>/ y el directorio subagents/ junto a él. El usuario puede preguntar por otra sesión; entonces pasa su id.

   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/usage.py            # la sesión actual (transcripción más reciente de este proyecto)
   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/usage.py <id-de-sesión>
   

3. El registro del proyecto. Los archivos de instrucción (CLAUDE.md, AGENTS.md), el backlog y el registro de decisiones si el proyecto los mantiene, y las memorias de feedback del agente para este proyecto (~/.claude/projects/<slug-del-proyecto>/memory/), para que un error repetido sea reconocido como repetición.

4. Debriefs anteriores. Los últimos tres informes en el directorio de informes (abajo). Por cada recomendación que hicieron, anota si se actuó sobre ella, si es recurrente o si se desconoce; un problema recurrente se escala en severidad.

Adecúa el esfuerzo al bloque: una sesión corta y limpia recibe un pase rápido; una sesión de varias semanas recibe el tratamiento completo y los cinco porqués en los patrones más grandes.

Qué examinar

Recorre estos cuatro grupos. Por cada hallazgo, cita el momento (qué se dijo o hizo, aproximadamente cuándo), explica por qué fue importante y pregunta "por qué" más allá del incidente hasta llegar a una causa de proceso o a un principio, o hasta que la respuesta salga del control del proyecto. Mantén separadas las observaciones y las prescripciones: una observación puede ser correcta mientras que la solución propuesta es incorrecta.

1. Eficiencia. Llamadas a herramientas redundantes o repetidas, lógica escrita a mano que un script o skill debería haber manejado, ciclos extra de compilación o prueba, trabajo que podría haberse agrupado, subagentes que se pasaron por alto o que valieron la pena, retrabajo después de compactación, trabajo en segundo plano que murió con la sesión.
2. Colaboración. Preguntas hechas demasiado pronto, demasiado tarde o nunca hechas; instrucciones permanentes no seguidas; ejemplos tomados literalmente cuando se pretendía una regla; verbosidad; si el agente dijo qué interpretación de una solicitud ambigua eligió; si las preguntas bloqueantes realmente bloquearon.
3. Corrección y disciplina. Afirmaciones hechas sin evidencia; restricciones descubiertas tarde; acciones destructivas o irreversibles sin confirmación; convenciones del proyecto pasadas por alto; las preguntas "qué escenario requiere esto" y "qué lo habría detectado" omitidas.
4. Transferir. Preferencias y decisiones que vale la pena guardar como memoria o documentación del proyecto; propuestas que son un skill, un workflow, un hook, una regla permanente o un elemento del backlog; herramientas que habrían facilitado el bloque; pasos que podrían automatizarse la próxima vez. Dos repeticiones escritas a mano señalan un activo reutilizable faltante.

Luego las dos partes que hacen que este skill sea personal:

• Coaching para la persona. ¿Cómo podría la persona que escribe los prompts haber sido más efectiva? ¿Qué movimientos suyos ayudaron más (nómbralos, para que se repitan) y cuáles costaron (alcance vago, una etiqueta faltante en un ejemplo, una decisión retenida que el agente necesitaba, una revisión omitida)? Escríbelo directamente a la persona, como lo haría un colega en un grupo de supervisión: específico, basado en evidencia, sin halagos y sin suavizar.
• Modelos y esfuerzo. A partir de los números: ¿fueron el modelo y el nivel de esfuerzo proporcionales al trabajo? ¿A dónde fueron los tokens (bucle principal, subagentes, workflows), y habría bastado un modelo más barato o un esfuerzo menor para partes de él? ¿Dónde valió la pena un alto esfuerzo?

Informe

Escribe el informe en el directorio de informes y muestra un breve resumen en la respuesta. El directorio es docs/debriefs/ en el repositorio actual cuando el repositorio tiene un directorio docs/, de lo contrario ~/.claude/debriefs/<slug-del-proyecto>/; el usuario puede nombrar otro. Nombre de archivo AAAA-MM-DD.md, con un sufijo -2 si ya existe uno.

Corto y denso: el lector es la persona que vivió la sesión, por lo que el informe recuerda en lugar de narrar. El matiz reside en la evidencia y la causa, no en la prosa que las rodea. Usa esta plantilla:

# Debrief <fecha>: <de qué trató el bloque>

Cobertura: <lo que el debrief pudo ver; compactación anotada>. Debriefs anteriores: <fechas o ninguno>.

## En cinco líneas
- <lo que logró el bloque>
- <qué lo hizo funcionar>
- <qué costó>
- <el coaching en una línea>
- <cuántas propuestas, y la que no es pequeña>

## Números
<un párrafo del script: duración, turnos, llamadas a herramientas con las principales, tokens de salida por modelo, subagentes, compactaciones>

## Lo que fue bien
- **<etiqueta de dos palabras>.** <el momento> → <lo que aportó>.

## Lo que costó
- 🔴 / 🟡 / 🟢 **<etiqueta>.** <el momento, una línea>.
  Causa: <la causa de proceso después de preguntar por qué>. <Solucionado, o lo que queda>.

## Coaching para <la persona>
Seguir haciendo: <los movimientos que ayudaron, como lista en una línea>.
1. **<hábito>.** <evidencia> y <qué hacer en su lugar>, una o dos oraciones.

## Modelos y esfuerzo
<un párrafo: proporcional o no, y los números que lo indican>

## Propuestas
| # | Propuesta | Destino | Esfuerzo | Decisión |
|---|---|---|---|---|
Destinos: regla en AGENTS.md o CLAUDE.md, memoria, skill, workflow, hook, backlog, la guía compartida, una herramienta a adoptar.

## Recomendaciones anteriores
| De | Recomendación | Estado (actuado / recurrente / desconocido) |

Severidad: 🔴 costó trabajo real o arriesgó daño; 🟡 costó tiempo o atención; 🟢 un hábito pequeño.

Reglas

• Solo un informe. No se escribe nada en archivos de instrucción, memoria o backlog hasta que el usuario apruebe una propuesta; luego aplica exactamente esa.
• Cada hallazgo cita un momento. Si no puedes señalar uno, descarta el hallazgo.
• No inflar: tres hallazgos reales superan a diez rellenos, y "este bloque fue bien" es un resultado válido.
• El coaching es para beneficio de la persona, por lo que debe ser sincero; también es privado por defecto, así que mantenlo fuera de cualquier cosa que la persona no haya pedido compartir.
• Lenguaje sencillo y procesable: escribe cada elemento de modo que una persona o un agente que no estuvo en la sesión pueda actuar sobre él. Nombra una práctica como un comportamiento (lo que alguien hace y lo que logra: "especifica el resultado, no la solución"), nunca con un apodo acuñado en la sesión ("la solución retenida", "escépticos", "a ojo"); si la abreviatura ayuda al reconocimiento, ponla después de la forma completa entre paréntesis. La prueba: ¿podría un colega copiar la línea en su propia guía y seguirla?
• Brevedad: una etiqueta en negrita, luego una línea de evidencia, luego la causa. Si un hallazgo necesita un párrafo, son dos hallazgos o aún no se comprende. Apunta a una pantalla por sección.
• Lecciones versus fricción: una lección es algo que le dirías a otro agente en otro proyecto; lo que aplica solo a esta sesión es fricción y va a los hallazgos, no a las propuestas para reglas permanentes.