aurumiles/Handoff

¿Qué hace Handoff?

Finaliza una sesión de trabajo escribiendo en disco un archivo que la sesión siguiente leerá para retomar exactamente desde donde lo dejamos. Se usa en lugar de /compact, nunca junto con él.

Por qué no /compact

/compact para escribir el resumen relee toda la conversación, y luego sustituye el historial con ese resumen. El prefijo cambia, por lo que la caché que ya se había construido muere, y a partir de ahí cada turno la reconstruye sobre un resumen de cuarenta turnos. No compra ahorro, compra continuidad y la hace pagar.

Un archivo de handoff hace lo contrario en tres frentes:

1. Cuesta menos. El archivo son unos pocos cientos de tokens en escritura y otros tantos en lectura, y la sesión nueva arranca desde un prefijo pequeño y limpio.
2. El usuario elige qué sobrevive. /compact decide solo y tira lo más valioso, es decir, los caminos ya probados que no funcionaron. Ningún resumen automático los conserva.
3. Permanece en disco. La tercera sesión sobre el mismo trabajo sabe qué hicieron la primera y la segunda. Un compact vive y muere dentro de su sesión.

Procedimiento

1. Reconstruye por ti mismo, no preguntes lo que puedes ver. Qué se ha tocado, qué se ha probado, qué ha fallado y por qué, qué decisiones se han tomado, dónde nos detuvimos: todo eso está en la conversación. En un repositorio git añade git status --short y git log --oneline -5.

2. Pregunta solo los dos huecos que no puedes deducir. Son el objetivo (qué se está construyendo y por qué, no qué se hizo hoy) y el siguiente paso deseado, que no siempre es el siguiente paso obvio. Si faltan, pregúntalos en una sola pregunta, con tu hipótesis ya incluida, de modo que baste responder "sí". Todo lo demás no se pregunta: si una sección está vacía se escribe ninguno y se sigue adelante, sin inventar problemas resueltos que no existieron.

3. Decide dónde escribirlo. En un repositorio de código: docs/handoff/{YYYY-MM-DD}-{slug}.md. En un vault o carpeta de notas (como este mismo proyecto, tu-sistema): una carpeta handoffs/ dentro del proyecto al que pertenece el trabajo. El {slug} son dos o tres palabras sobre el trabajo, no sobre la fecha. Si ya existe un handoff con el mismo slug no lo sobrescribas: el archivo nuevo incrementa un campo seq y coloca el anterior en prev, de modo que la cadena se lea hacia atrás.

4. Escribe el archivo con este frontmatter — type: handoff, date, status, seq, prev, tags — y estas secciones, en este orden:

• Objetivo: qué se está construyendo y por qué, dos o tres líneas, incluyendo la razón.
• En qué punto estamos: el estado real ahora. Qué funciona, qué está a medias, qué no ha empezado.
• Qué hemos probado que NO ha funcionado: la sección más importante del archivo. Cada camino descartado con el motivo. Sirve para impedir que la sesión siguiente lo vuelva a intentar desde cero.
• Problemas encontrados y cómo los resolvimos: solo aquellos que se repetirían. Síntoma, causa, corrección.
• Decisiones tomadas: qué se ha elegido y qué se ha descartado, con una línea de por qué. Una decisión sin la alternativa descartada se vuelve a discutir desde cero a la semana siguiente.
• Archivos tocados: rutas, con una línea sobre qué ha cambiado en cada uno.
• Hacia dónde queremos ir: el siguiente paso, escrito en imperativo. Luego el siguiente, si ya está claro.
• Cosas que saber antes de tocar algo: trampas, comandos que deben lanzarse de cierta manera, cosas que parecen rotas y no lo están. Si no las hay, ninguna.

5. Finaliza imprimiendo en el chat la línea de reanudación, lista para pegar en una sesión nueva: Lee {ruta} y reanuda desde "Hacia dónde queremos ir". Más una línea para decir que en este punto se puede hacer /clear y que la reanudación solo costará ese archivo.

Cuándo NO se usa

Una skill que siempre se usa es una skill que se usa al azar.

• Cambio de tarea sin continuidad → /clear, no hace falta ningún handoff.
• Se ha tomado un camino equivocado en los últimos turnos → /rewind, que vuelve a un punto que la caché ya conoce.
• Se retoma en breve y sin actualizaciones intermedias → /rename más /resume.
• El trabajo continúa otro día u otra semana → esta skill.

Esta skill no ejecuta /clear por el usuario: solo lo sugiere.