Agentic QA · Skill de sesión
Cuando la ventana de contexto se llena, la sesión se compacta en un archivo y una sesión nueva sigue exactamente donde quedó. Para vos, es como si la ventana se hubiera estirado en vez de reiniciarse.
Cuándo usarla · 2 de 13
| Lo que querés hacer | Qué es en realidad | Con qué |
|---|---|---|
| Pasarle una tarea acotada a otra sesión y supervisarla | Orquestación: Task, Dispatch, mailbox; el trabajo vuelve | /orca-orchestration |
| Entregar un trabajo y desentenderte | Transferencia de una TAREA, en una dirección, sin retorno | la guía orca-cli del binario |
| Recordar una decisión el mes que viene | Hecho durable entre sesiones, por proyecto | Engram (mem_save) |
| Achicar la ventana y seguir | Compactación del harness: con pérdida, no direccionable, no la controlás | nada que hacer |
| Pasar la SESIÓN entera a su sucesora | esta skill | /session-handoff |
La diferencia que importa: la compactación guarda lo que un resumidor juzgó relevante. El handoff guarda lo que necesita la próxima en actuar, y lo escribe la única parte que conoce la diferencia.
Mapa · 3 de 13
Disparo
El dueño lo pide
ventana cerca del umbral
o trabajo que sigue
Paso 1
Capturar
capture-contract.md
§0 a §9, ninguna se omite
Paso 2
Escribir
templates/handoff.md
→ <nombre>-handoff-NN.md
Paso 3
Lanzar la sucesora
successor-launch.md
misma worktree y harness
Cómo arranca la sucesora (paso 3)
Con runtime
La sesión abre la terminal
anuncia antes de lanzar
Sin runtime
Imprime la línea
el dueño la pega · prompt idéntico
Últimos actos de la predecesora
1
Confirmar
la sucesora arrancó y tiene el archivo
2
Persistir lo durable
mem_session_summary
3
Parar
cerrarla es decisión del dueño
Disparo · 4 de 13
Escribí uno cuando
Manual es el disparador primario
El humano ve que la ventana se llena, lo dice y la skill corre. Sin polling, sin insistir, sin gastar tokens adivinando.
No lo escribas
Si lo que falta entra cómodo en la ventana. Producir un handoff cuesta una porción real de contexto, y una sucesora lanzada antes de tiempo paga el arranque por nada.
El umbral es tuyo
Es un juicio del dueño sobre dónde se degrada este modelo, no configuración del proyecto: queda en la conversación, nunca en una clave de yaml.
Disparo · 5 de 13
Ningún harness le pasa al agente el tamaño actual del contexto. Dos de los tres lo exponen fuera del loop del modelo: un modo automático sería cableado nuevo, no un campo esperando a ser leído.
| Harness | Mejor señal disponible | Qué trae |
|---|---|---|
| Claude Code | el JSON que recibe la status line | context_window.used_percentage y el tamaño de la ventana |
| OpenCode | un plugin suscrito a message.part.updated | tokens.input / tokens.output de cada step-finish, acumulables |
| Codex CLI | solo el evento PreCompact | ningún número; la ventana ya está llena |
La compactación es el momento equivocado
Los tres avisan que la compactación es inminente, pero ahí la ventana ya se agotó: el handoff lo escribiría una sesión a punto de truncarse, con el juicio degradado del que el handoff existe para escapar.
Si algún día se habilita
Pregunta una vez, en dos líneas, y acepta un no sin volver a preguntar en esa sesión. Nunca escribe un handoff sin que se lo pidan.
Paso 1 · Capturar · 6 de 13
Cada sección es obligatoria y en este orden. Una sección vacía se escribe con una línea none y su motivo: omitida y olvidada se ven iguales, y la sucesora no puede preguntar cuál pasó.
| § | Sección | Qué evita |
|---|---|---|
| 0 | Tu PRIMERA tarea. Una sola, no un menú. Criterios del dueño citados, numerados. | una sucesora que re-decide lo que ya estaba decidido, y elige distinto |
| 1 | Identidad y autoridad. Qué delegó el dueño y qué se reservó; harness, worktree, label, política de push con su valor resuelto. | re-preguntar lo delegado, o asumir una autoridad que no tiene |
| 2 | Qué se construyó. Un párrafo por unidad, con SHAs, PRs y paths; qué está pusheado y qué solo local. | rehacer trabajo que ya estaba terminado |
| 3 | Decisiones con su porqué. Alternativas descartadas y quién decidió. | revertir una elección deliberada creyendo que fue un descuido |
| 4 | Gotchas y observaciones. Cada una measured o read, con la versión o fecha en que vale. | pagar dos veces el mismo costo; es la sección de más valor y la que más flaca se escribe |
Paso 1 · Capturar · 7 de 13
| § | Sección | Qué evita |
|---|---|---|
| 5 | Skills, herramientas y MCPs usados. Tabla con la columna Load next session? respondida por fila, con motivo. | recargar todo (y quemar la ventana nueva) o no cargar nada (y adivinar sintaxis) |
| 6 | Archivos a leer, en orden. Paths absolutos, para qué sirve cada uno, qué secciones. | convertir la lectura en un problema de búsqueda ya resuelto |
| 7 | Estado vivo que heredás. Workers corriendo, mailboxes, PRs en vuelo, runs. Todo marcado PERISHABLE. | actuar sobre un mundo que ya cambió: acá es donde los handoffs se rompen |
| 8 | Pendientes en orden de prioridad. Lo que el dueño ya decidió, separado de lo que espera su decisión. | empezar por lo interesante en vez de lo importante |
| 9 | Convenciones del dueño. Cómo presentar decisiones, idioma, registro, memoria; y el umbral del próximo handoff. | reaprender preferencias equivocándose primero |
§9 cierra el linaje: le dice a la sucesora a qué umbral escribe su propio -handoff-NN+1 y lanza la suya. Si no se perpetúa solo, el linaje termina en la primera sesión que se olvida.
Paso 1 · Capturar · 8 de 13
measured / read / predicted
Medido: esta sesión lo corrió y leyó la salida. Leído: salió de un documento y se le creyó. Una rama predicha contada como hecho manda a la sucesora por un camino que ya no existe.
PERISHABLE + hora
Lo que decae entre la escritura y la lectura lleva la hora en que se midió. La instrucción es re-verificar y después actuar, nunca al revés.
Perecedero antes que prioridad
Si un ítem vivo necesita atención antes que la lista de prioridades, se dice en la misma línea. Un worker esperando no puede esperar al orden de §8.
Ids copiados
Run, dispatch, terminal, sesión, PR, clave del tracker, SHA: verbatim, en backticks, listos para pegar. "El worker de antes" no es un id.
Paths absolutos
La sucesora puede arrancar en otro directorio.
Lo que NO está hecho
Con su motivo. Un handoff que se lee como un éxito sin cortes escondió algo, y lo escondido es lo que muerde.
Paso 2 · Escribir · 9 de 13
Nombre
<sesión-predecesora>-handoff-NN.md. El nombre de la sucesora es ese archivo sin la extensión: esa es toda la regla. El de la predecesora sale del session= de la línea AGENT IDENTITY: que inyecta el hook; si dice unknown, se le pide un nombre al dueño.
NN
Dos dígitos desde 01. Se lista el directorio del primario antes de elegir: nunca se supone, nunca se cuenta desde la .session/ de una worktree.
Descartable
.session/ está en gitignore: un handoff describe una sesión, no es un registro del proyecto. Se escribe en inglés y no se borra el anterior. Uno escrito por error dentro de una worktree lo rescata bun run worktree:audit --rescue antes de borrarla.
Paso 3 · Lanzar · 10 de 13
Con un runtime alcanzable
Antes de lanzar verifica tres cosas: el binario está y el runtime responde; el archivo existe completo en su path final; el destino es la misma worktree y el mismo harness.
Después abre una terminal en esa worktree con la línea de lanzamiento del harness (Claude lanza Claude, OpenCode lanza OpenCode, Codex lanza Codex), con el nombre de la sucesora y un primer prompt.
Te lo anuncia antes de dispararlo y te dice qué terminal lo lleva: va a aparecer una segunda sesión en tu tablero.
Sin runtime
Todo igual salvo quién abre la terminal: imprime la línea, dice dónde está el archivo y vos la pegás. El prompt es idéntico byte a byte: el camino que nadie ejercita es el que se rompe en silencio.
El primer prompt
Read `<absolute path to the handoff>` top to bottom and continue that session exactly where it stopped.
Si §0 exige un orden, se repite en el prompt: un puntero a un archivo se lee como referencia; una instrucción en el prompt, como instrucción.
Límites · 11 de 13
| Handoff (esta skill) | Orquestación (/orca-orchestration) | Memoria (Engram) | |
|---|---|---|---|
| Qué se mueve | la sesión entera | una tarea acotada | un hecho durable |
| La que la origina | termina | sigue trabajando y supervisa | sigue igual |
| Canal después | ninguno, por diseño | mailbox, preguntas, respuestas | búsqueda en próximas sesiones |
| Objetos del runtime | una terminal | Run, Task, Dispatch, worker | ninguno |
El error típico
Usar los verbos de orquestación para lanzar la sucesora crea un worker supervisado que después tenés que liberar y cerrar, sin motivo. La familia correcta es la de terminal y worktree.
Y no es un briefing
Un briefing de 7 componentes acota una tarea; un handoff trasplanta una sesión. Lo durable igual se guarda en memoria al final, porque el handoff es descartable y la memoria no.
Salvaguardas · 12 de 13
| Regla | Por qué |
|---|---|
| Lanzar la sucesora antes de escribir el archivo | arrancaría leyendo un archivo que no existe |
| Cambiar de harness entre predecesora y sucesora | un handoff pensado para las convenciones de un agente es un problema de traducción para otro |
| Borrar el handoff anterior | el linaje es la pista de auditoría |
| Cerrar su propia terminal | terminar la predecesora es decisión del dueño; si se cierra sola no puede avisar que el handoff falló |
| Escribir un handoff sin que se lo pidan | el momento es un juicio sobre el trabajo, y ese juicio lo tiene el humano |
| Escribir secretos en el archivo | nombra la variable donde vive una credencial, nunca su valor; una cookie, un token o la ruta de un archivo de .auth/ quedan fuera (Regla #1) |
| Atribución a la IA, en cualquier parte | Regla #3; el handoff es un artefacto del repo, en inglés (Regla #14) |
| Copiar la gramática del CLI de orquestación al repo | la copia se desincroniza en la próxima versión del binario |
Cierre · 13 de 13
Cómo se invoca
Claude Code: /session-handoff.
OpenCode y Codex: cargá la skill session-handoff.
En los tres hosts también la disparan frases como "hagamos el handoff" o "pasa el contexto a otra sesión". No tiene modos.
Qué lee
Su contrato de captura y su plantilla · el directorio .session/handoffs/ del primario, para elegir NN · .agents/README.md, "Checkout roots".
Qué deja
Un <sesión>-handoff-NN.md en el primario · una sesión sucesora en la misma worktree y harness · lo durable en memoria vía mem_session_summary.
Canon
.agents/skills/session-handoff/SKILL.md y sus referencias: capture-contract.md (las secciones), successor-launch.md (el lanzamiento), auto-trigger.md (qué expone cada harness), templates/handoff.md (el esqueleto).
Relacionadas: /orca-orchestration para delegar una tarea y supervisarla · agentic-qa-core/references/session-footer-contract.md para lo que una sesión reporta al cerrar.