eai-org/agent-toolkit

Handover (Entrega)

Empaqueta un cambio terminado para que sus revisores nunca tengan que reconstruir la intención a partir del diff. Escribe para un revisor que solo tiene el diff y nada más — ni documentos de planificación, ni sesión, ni conocimiento de que existan.

Resolver la tarea

La entrada es cualquier referencia parcial — id de ticket, slug, ruta de un artefacto de planificación — o nada, que significa la tarea de la sesión; en una sesión nueva, infiérela del nombre de la rama y de los commits recientes. Resuélvela al hogar de planificación de la tarea: su directorio <id>-<slug>/ dentro del directorio de planificación del proyecto, o sus archivos planos <id>-<slug>.* en un directorio familiar compartido. Una coincidencia clara → procede, indicando el hogar y los artefactos encontrados. Si se infiere o hay varios candidatos (-vN, …) → confirma primero. Una referencia explícita que no coincide con nada local → detente y pregunta; nunca adivines.

Reunir

Lee lo siguiente, omitiendo lo que no exista:

1. Artefactos de la tarea — cada <id>-<slug>*.md en el hogar de planificación: ticket, requisitos, plan, registro de decisiones, rondas previas de revisión y entrega, lo que sea que coincida.
2. Tickets relacionados — solo un salto: padre (subiendo solo más allá de contenedores delgados), predecesores/sucesores directos, relaciones explícitas, hermanos del directorio familiar; nunca expandas sus propias relaciones. Primero los .TICKET.md locales; obtén del rastreador solo cuando una relación no tenga archivo local y parezca relevante para un por qué — si dudas si obtenerlo, pregunta.
3. La sesión, cuando produjo el cambio: decisiones, giros, restricciones.
4. El diff contra el objetivo, más los asuntos de los commits.

Cada fuente una vez, sin profundizar más de lo que el artefacto necesita: hojea el diff completo, lee en profundidad solo los archivos que nombrarás en la Guía de revisión, y nunca reconstruyas el historial commit por commit — qué commit cambió qué es trabajo del diff, no tuyo.

Luego compara los pasos del plan y los criterios de aceptación contra el diff en ambos sentidos — planeado pero ausente, presente pero no planeado. Terminado cuando cada fuente está leída o confirmada como ausente y cada elemento planeado está cotejado.

Nunca inventes justificaciones

Afirma un "por qué" solo cuando una fuente lo proporciona. Una desviación que nada explica se pregunta al autor una vez; si no hay respuesta o no se puede preguntar, se envía marcada en lenguaje claro ("nada registra por qué — vale la pena confirmar"), ya que puede ser una brecha no intencionada en lugar de una decisión. La fuente es tu puerta, no la lectura del revisor: decide lo que puedes escribir, y nunca aparece en el texto. Cuando no estés seguro, siempre pregunta. Nunca adivines.

El artefacto

<slug>.HANDOVER.md en el hogar de planificación; si ya existe → <slug>.HANDOVER-2.md, -3, … — nunca sobrescribas. Sin hogar de planificación → presenta el contenido y pregunta dónde guardarlo. Su cuerpo está listo para pegarse como descripción del PR y es autónomo:

• Menciona solo lo que el revisor pueda abrir — una URL del rastreador, o un archivo que verifiques que está commiteado en la rama. Todo lo demás — documentos de planificación, registro de decisiones, sesión, hashes de commits — ni se enlaza ni se nombra: escribe lo que dice ("esto debía …"), nunca dónde lo dice.
• Los tickets relacionados no se mencionan a menos que un por qué dependa de uno ("construido así para preparar ") — entonces cita su URL del rastreador.
• En una pantalla, ~400 palabras; los límites a continuación son máximos, no objetivos.
• Lenguaje claro orientado al revisor, nunca el vocabulario de esta habilidad. Antes de redactar, invoca realmente use-conversational-language — recitar sus reglas de memoria no cuenta.

Secciones, omitidas solo cuando están realmente vacías:

1. Qué y por qué — 2–3 líneas.
2. Decisiones que vale la pena conocer — como máximo 5 líneas, cada una: qué se eligió o qué se desvía del plan, su por qué o la marca de por qué ausente, y dónde en el código verlo.
3. Guía de revisión — los pocos archivos donde el criterio importa y por qué; el resto nombrados como mecánicos.
4. Brechas conocidas — como máximo 3: deficiencias, suposiciones, preguntas abiertas.

Terminado cuando cada sección está llena u omitida a sabiendas, nada suena como verificado que no lo estuviera, y nada en el texto apunta a algo que el revisor no pueda abrir.

Límites

• No modifiques ningún archivo fuente; el documento de entrega es el único archivo escrito.
• Nunca hagas push, ni abras o comentes en un PR — la publicación es decisión explícita del usuario.