handoff

Handoff de sesión

Tu objetivo es escribir un documento de handoff que permita a un sucesor —que tiene el repositorio y todo el historial de git, pero ninguna memoria de esta conversación— retomar el trabajo sin redescubrir nada.

Principio rector: puntero, no transcripción. Captura solo lo que el sucesor NO puede reconstruir barato por sí mismo (decisiones, intención, callejones sin salida, gotchas). Para todo lo demás, apunta al artefacto (ruta y líneas). No copies bloques de código largos ni vuelques la conversación.

Segundo principio: un handoff cuenta una historia, no es un volcado de datos. Una base de datos guarda hechos; un handoff explica qué está pasando y por qué.

Paso 1 — Reúne estado real con la herramienta Bash (ejecútalo, no lo recuerdes)

Corre estos comandos y lee la salida real. Son de solo lectura:

git branch --show-current
git status -s
git log --oneline -20
git diff --stat

Si necesitas ver cambios concretos, usa git diff acotado. Nunca ejecutes git add, git commit, git push ni ningún comando que mute el repositorio: un handoff se lee, no cambia nada.

Si hay trabajo sin commitear o sin pushear, anótalo de forma destacada al inicio del documento y recuerda al usuario revisarlo antes de continuar — pero no hagas commit tú.

Paso 2 — Prepara el destino

El handoff se escribe en el proyecto del usuario, no en el directorio del plugin. Crea el directorio si no existe:

mkdir -p "${CLAUDE_PROJECT_DIR:-.}/.claude/handoffs"

El nombre del archivo lleva un timestamp para no pisar handoffs anteriores:

${CLAUDE_PROJECT_DIR:-.}/.claude/handoffs/handoff-<YYYYMMDD-HHMMSS>.md

Obtén el timestamp con date +%Y%m%d-%H%M%S vía Bash.

Paso 3 — Escribe el documento

Usa la plantilla de abajo. Omite cualquier sección que quede vacía — una sección rellena de paja es peor que su ausencia. El núcleo (Objetivo, Estado, Decisiones, Próximos pasos, Gotchas) es obligatorio; el resto, opcional.

Antes de escribir, redacta secretos, tokens, claves, contenido de .env y credenciales en URLs. Sé conservador: ante la duda, redacta. El archivo puede entrar en git.

Plantilla

# Handoff: <título de la tarea> — <YYYY-MM-DD HH:MM>

> ⚠️ <SOLO si aplica: trabajo sin commitear en X, Y. Revisa antes de continuar.>

## Objetivo
<1–2 frases: qué se intenta lograr y por qué importa. Sin esto el sucesor
optimiza lo incorrecto.>

## Estado actual
<Narrativa breve, 3–5 frases: dónde estamos AHORA y cómo llegamos aquí. Si algo
está a medias, di exactamente dónde se cortó, con archivo:línea.>

## Decisiones tomadas
<La sección de mayor valor. Para cada decisión relevante:
- **Qué** se decidió.
- **Por qué** (el razonamiento).
- **Qué se descartó** y el trade-off que lo hizo perder.
Esto es lo que el sucesor NO puede reconstruir mirando el código.>

## Qué funcionó / qué no
<Enfoques que probamos y fallaron, para que no se reintenten callejones sin
salida. Y lo que sí funcionó y por qué.>

## Archivos relevantes
<Punteros, no contenido. Ruta + rango de líneas + qué hay ahí:
- `src/foo/bar.ts:L40-L88` — nueva lógica de validación, falta el caso vacío.
- `src/foo/baz.test.ts:L12` — test que reproduce el bug.>

## Gotchas / avisos
<Lo no obvio que ahorra horas: estado del entorno, rate limits, efectos
colaterales, supuestos frágiles, configuración especial.>

## Próximos pasos
<Cola priorizada y DECLARATIVA, no imperativa: describe qué falta, no ordenes
acciones a ciegas. Ej.: "La paginación aún no maneja la última página parcial"
— no "implementa la paginación".>

## Prompt para retomar
<Texto pegable en el hilo nuevo. Da el contexto como información, no como
órdenes. TERMINA siempre con:
"Antes de actuar, lee con la herramienta Read todos los archivos de la sección
'Archivos relevantes'. Después espera mis instrucciones.">

Paso 4 — Cierra

Tu única salida final al usuario debe ser la ruta del archivo creado. No vuelques su contenido en la conversación: ese es justo el contexto que intentamos descargar. La última línea de tu respuesta es la ruta y nada más:

Handoff guardado en .claude/handoffs/handoff-<timestamp>.md

---

Notas de diseño

Estas decisiones provienen de comparar ~15 skills de handoff públicas y pasarlas por un filtro adversarial. Lo que entró tiene consenso multi-fuente; lo que se quedó fuera era de una sola fuente o falsa precisión.

• Núcleo de 5 secciones con consenso fuerte: Estado, Decisiones (con descartadas), Próximos pasos, Gotchas y punteros-no-transcripción aparecen repetidos en fuentes independientes. El decision log con opciones rechazadas es el patrón más universal de todos.
• Narrativa LLM, no extracción programática. Volcar "los últimos N mensajes" produce exactamente el data-dump sin contexto que todos dicen evitar.
• Archivo nuevo con timestamp, no overwrite ni append-a-uno-gigante: preserva la historia sin inflar un único fichero ni provocar colisiones.
• Escribe en el proyecto del usuario (${CLAUDE_PROJECT_DIR}), nunca en el directorio del plugin.
• No auto-commit: commitear por el usuario es destructivo y sorprendente.
• Omitir secciones vacías vence a la plantilla rígida que se rellena de paja.

Deliberadamente fuera de alcance (opt-in, no aquí)

Hooks PreCompact/SessionStart para disparo automático, Stop-hook que bloquea el cierre, umbrales numéricos de contexto, deduplicación por similitud, frontmatter con cadena de SHAs y modos especializados: over-engineering que añade fragilidad sin señal proporcional para una skill de handoff de propósito general.