Recap Visual (BuilderIO/visual-recap)

Recap Visual

/visual-recap crea un plan visual construido a partir de un diff, no hacia uno. Es al revés de la planificación hacia adelante: en lugar de describir el cambio que estás a punto de realizar, describes el cambio que acaba de realizarse, a una altitud mayor que la revisión línea por línea. El mismo modelo de datos del plan sirve para ambas direcciones: los cambios de esquema, API, archivo y arquitectura se convierten en los mismos bloques data-model, api-endpoint, file-tree y diagram que usaría un plan hacia adelante, solo que ahora resumen el trabajo existente. Un revisor escanea la forma del cambio antes de dedicar atención a las líneas literales.

Publicar como un plan nativo de agente — nunca inline

El entregable es SIEMPRE un Plan Nativo de Agente publicado, creado con create-visual-recap en el conector Plan MCP — NUNCA contenido de chat inline (ni prosa en Markdown, un boceto ASCII, una tabla, un "wireframe" delimitado, o un resumen del tipo "aquí está el recap"). Todo el valor de un recap es el plan alojado, interactivo y anotable; un resumen inline no es un recap degradado, es lo que un recap reemplaza. Si las herramientas plan (o las heredadas agent-native-plans) no son visibles, descúbrelas a través del tool_search del anfitrión primero; si aún así faltan, DETENTE y dale al usuario el paso de reconexión específico del cliente, en lugar de improvisar un recap inline. Antes de publicar, o cada vez que aparezca un error de conector o autenticación, LEE references/connection.md en este directorio de la habilidad — es la fuente única de verdad para la regla de nunca inline, el descubrimiento de conectores y los pasos de reconexión por cliente. El modo de privacidad de archivos locales (abajo) es la única excepción.

Modo de privacidad de archivos locales — lee references/local-files.md

Cuando el usuario no quiera escrituras en la base de datos de planes alojada — sin escrituras en BD, sin publicación en Plan MCP, recaps completamente locales/offline/privados, o AGENT_NATIVE_PLANS_MODE=local-files — no llames a ninguna herramienta de plan alojada excepto la búsqueda en el catálogo de solo esquema get-plan-blocks. Lee el diff con los ayudantes locales recap collect-diff / scan / build-prompt --local-files, crea una carpeta MDX local (establece kind: "recap" y localOnly: true), y previsualízalo con plan local check, plan local serve --kind recap, y plan local verify --kind recap. Antes de usar el modo de archivos locales, LEE references/local-files.md en este directorio de la habilidad — es la fuente única de verdad para el contrato completo.

Cuándo usarlo

Construye un recap cuando un PR o commit es grande, multi-archivo, o toca esquemas, contratos de API o arquitectura, y un revisor se beneficiaría de ver el cambio mapeado a bloques estructurados antes de leer el diff en bruto. Una GitHub Action puede generar uno automáticamente a partir del diff de un PR; un agente puede generar uno a petición ("recap este PR", "muéstrame qué cambió esta rama"). Omítelo para diffs pequeños, de un solo archivo u obvios — un recap es sobrecarga de revisión, y un cambio pequeño se revisa más rápido como diff simple.

Recapitular toda la unidad de trabajo

Cuando se invoca /visual-recap en un hilo de chat después de que ya ha ocurrido trabajo, el alcance predeterminado es toda la unidad de trabajo/hilo actual, no solo el mensaje de usuario más reciente, la acción de herramienta o la corrección de seguimiento. Reúne los cambios propiedad del hilo a lo largo de la conversación: trabajo de implementación original, correcciones de errores posteriores, seguimientos de UI, pruebas, changesets, actualizaciones de habilidades/instrucciones, artefactos de plan/código generados, y cualquier corrección de importación/enlace local necesaria para que el recap se abra.

Usa el diff actual más el contexto de la conversación para separar los cambios propiedad del hilo del trabajo sucio no relacionado que existía antes del hilo. Excluye ediciones preexistentes no relacionadas. Si el alcance es genuinamente ambiguo y no se puede inferir, indica la suposición o haz una pregunta concisa antes de publicar.

Al actualizar un recap existente después de recibir comentarios, revisa el recap para que aún cubra todo el hilo/unidad de trabajo más la nueva corrección. No reemplaces un recap amplio con un recap limitado solo de los últimos comentarios a menos que el usuario lo solicite explícitamente para ese alcance más limitado.

Mantén el cuerpo del recap ligero

No agregues bloques de prosa de introducción estándar, descargo de responsabilidad, procedencia o resumen al cuerpo del plan generado. En particular, no crees un bloque rich-text solo para decir que el recap es una ayuda, que el revisor aún debe revisar el diff, cuántos archivos cambiaron o qué ref/árbol de trabajo generó el recap. El título del plan, el resumen breve y el file-tree (que lleva las estadísticas de cambio por archivo) ya transmiten eso.

Solo agrega bloques de prosa cuando le digan al revisor algo específico sobre el cambio que los bloques estructurados no transmiten: el objetivo, un riesgo de compatibilidad real, una decisión importante visible en el diff o una nota de revisión fundamentada.

Los recaps deben ser sustanciales

Ligero no es lo mismo que delgado. Un recap no es un único wireframe más una oración — eso subestima al revisor tanto como la prosa estándar lo sobreestima. Junto con el titular visual/estructural (wireframes, data-model, api-endpoint, diagram), un recap sustancial también lleva la evidencia de implementación:

• Un breve inventario de superficie/estado antes de la autoría: lista las rutas cambiadas, componentes, popovers/diálogos, estados de rol/acceso, estados vacío/error y abstracciones compartidas visibles en el diff. El recap final debe representar cada elemento significativo con un bloque u omitirlo intencionalmente porque es pequeño, redundante o no visible para el usuario.
• Un file-tree de los archivos cambiados con el indicador change de cada entrada, para que el revisor vea la huella del trabajo de un vistazo.
• Los diff divididos de los archivos CLAVE cambiados, agrupados bajo un encabezado rich-text ## Key changes en un solo bloque horizontal de tabs (la orientación predeterminada, un archivo por pestaña), con un summary de una línea y algunas annotations en cada uno — para que el revisor pueda pasar de la forma de alta altitud directamente al código que soporta la carga. Usa pestañas de archivo horizontales, no un riel lateral vertical, para que el archivo seleccionado tenga suficiente ancho para el diff lado a lado.

Omite el apéndice de diff solo para un cambio genuinamente pequeño que se revise más rápido como diff simple (ver "Cuándo usarlo"); para cualquier cambio que valga la pena recapitular, el árbol de archivos y los diffs de cambios clave pertenecen al plan.

Forma canónica y presupuestos

Un recap sólido sigue un esqueleto, de arriba a abajo:

1. Titular de impacto en UI — wireframes primero, cuando el diff cambió la UI renderizada.
2. Narrativa corta de resultado (rich-text): qué cambió y por qué, 1-3 párrafos.
3. Bloques data-model / api-endpoint para cambios de esquema y contrato.
4. file-tree de los archivos cambiados con indicadores change.
5. ## Key changes — un bloque horizontal de tabs con diff / annotated-code.

Presupuestos que mantienen el recap revisable:

• 3-8 pestañas de cambio clave. Menos de 3 en un cambio grande subestima al revisor; más de 8 deja de ser un resumen.
• Mantén cada extracto de diff/código anotado enfocado — prefiere menos de ~150 líneas por pestaña; resume o enlaza el resto de un archivo largo en lugar de volcarlo.
• Título de máximo ~70 caracteres; resumen breve de 1-3 oraciones.

Estos presupuestos también son el techo de costo: no los excedas en nombre de la minuciosidad, y no releas el diff completo después del pase secuencial inicial — trabaja a partir de las notas tomadas durante ese pase.

BUENO. Un cambio de autenticación de 25 archivos: Wireframes Antes/Después de la superficie de inicio de sesión, una narrativa de dos párrafos, un data-model consciente del diff de la tabla de sesiones, un api-endpoint para la nueva ruta de actualización, un file-tree con indicadores de cambio y ## Key changes con cinco pestañas enfocadas, cada una con un summary de una línea y algunas anotaciones en los fragmentos que soportan la carga.

MALO. Un volcado de diff gigante sin segmentar sin resúmenes ni anotaciones; o un recap disperso de tres bloques de un cambio de 40 archivos (un wireframe, una oración, una lista de archivos) que obliga al revisor a volver al diff en bruto de todos modos.

El impacto en UI necesita wireframes

Cuando el diff cambia la UI renderizada, el diseño, la densidad, el estado visual, las afordances de interacción, la navegación, los controles, los menús, los diálogos o los tokens de diseño, el recap DEBE incluir uno o más wireframes. La prosa y los diffs de archivo no son un sustituto para mostrar qué cambió visualmente.

Antes de elegir wireframes, realiza un pase de cobertura de UI a partir del diff:

• Identifica la superficie de entrada donde aparece el cambio, como un encabezado de página, fila de lista, barra de herramientas, shell de ruta o activador de menú.
• Identifica la superficie de interacción que se abre o cambia, como un popover, diálogo, pestaña, hoja, menú desplegable, editor inline o toast.
• Identifica el destino resultante o el estado persistente, como una página pública, vista de solo lectura, estado vacío, estado de error, estado de carga, estado de permiso denegado o estado guardado/compartido.
• Identifica variantes de acceso o rol cuando cambian los permisos. Las diferencias entre propietario/admin/editor versus visor/no administrador son comportamiento visual y necesitan una matriz compacta, pares de wireframes o una secuencia de estados claramente etiquetada.

Para PRs con mucha UI, un único antes/después de la superficie de entrada no es suficiente. Muestra el punto de entrada cambiado, la superficie de interacción principal cambiada y el estado resultante/destino. Agrega más estados cuando el diff agrega pestañas, controles basados en roles, visibilidad pública/privada, flujos de invitación/gestión, controles destructivos o ramas de vacío/error.

Elige la superficie visual más pequeña que haga la revisión clara:

• Usa un par de wireframes Before / After cuando el revisor se beneficie de una comparación directa, como un control eliminado o agregado, un estado cambiado, densidad de diseño, orden, navegación o un reemplazo de componente visible. references/wireframe.md es dueño de cómo diseñar ese par (columnas vs. pila vertical según la geometría).
• Usa un wireframe solo del después cuando el cambio sea puramente aditivo o el estado "antes" solo mostraría ausencia sin agregar valor de revisión.
• Usa más de dos wireframes cuando el cambio de UI dependa del flujo, sea responsivo o tenga estado; muestra los estados significativos en orden en lugar de forzar un único par antes/después.
• Para superficies pequeñas como menús, popovers, diálogos, toasts o paneles, usa la surface correspondiente (popover, panel, etc.) y muestra la sub-superficie enfocada. No redibujes una página completa a menos que la colocación en la página sea en sí misma parte del cambio.

Fundamenta cada wireframe en el comportamiento de UI cambiado, los nombres de componentes, las rutas de archivo y las etiquetas/estados visibles en el diff. Si los píxeles exactos se infieren en lugar de capturarse, indícalo en el pie de foto del wireframe o en una anotación concisa. Para recaps locales/manuales, importa o actualiza la fuente del plan que contiene los wireframes para que el recap renderizado se abra con la UI visual disponible.

Calidad del wireframe — lee references/wireframe.md

Los wireframes de UI de recaps/planes deben cumplir un estricto estándar de calidad: cromo de ancho completo, barras inferiores fijadas, contenido real del producto, comparabilidad antes/después, el ajuste preestablecido surface correcto, tokens --wf-* en lugar de hexadecimales y sin etiquetas <html>/<style>/font. Antes de crear CUALQUIER wireframe / <Screen> / WireframeBlock, LEE references/wireframe.md en este directorio de la habilidad — es la fuente única de verdad para la calidad del wireframe HTML, compartida palabra por palabra con /visual-plan y /visual-recap. No crees wireframes de memoria.

Usa el formato estándar WireframeBlock / <Screen> para que el visor del Plan sea dueño del marco de superficie, el tema y la alternancia entre boceto y limpio. Los wireframes HTML son apropiados cuando la precisión de la colocación importa, especialmente popovers, menús, diálogos y formularios densos. Para wireframes HTML, mantén renderMode sin establecer o en wireframe a menos que se requiera explícitamente un mockup editable solo de diseño, porque renderMode="design" deshabilita la superposición de boceto tosco.

Cuando una herramienta de navegador esté disponible, renderiza un recap de impacto en UI en el visor del Plan e inspecciónalo visualmente con el tema actual antes de compartirlo. Si alguna etiqueta, anotación, barra de herramientas o contenido del wireframe se superpone con otro elemento, corrige el MDX y vuelve a importarlo antes de informar el enlace. Limita esto a un pase de renderizar e inspeccionar más, como máximo, una corrección y re-renderización; no sigas iterando más allá de eso a menos que el usuario lo solicite explícitamente. Una captura de pantalla de coincidencia de texto no es suficiente; inspecciona visualmente la imagen capturada. Cuando no haya navegador disponible (por ejemplo, un agente CI sin cabeza), indícalo en la entrega del recap.

Recaps de lienzo superior — lee ../visual-plan/references/canvas.md

Cuando un recap incluya un lienzo superior, guión gráfico o vista de flujo, LEE ../visual-plan/references/canvas.md antes de crear canvas.mdx. Los artboards del lienzo del recap deben usar la misma ruta de wireframe HTML que los wireframes buenos del cuerpo del documento: <Screen surface="..." html={...} /> con un fragmento HTML semántico. No crees hijos de kit-tree nuevos como <FrameScreen>, <Card>, <Row>, <Title> o <Btn> dentro de las etiquetas <Screen> del lienzo. Esos componentes son marcado de compatibilidad heredado para planes antiguos; en guiones gráficos de lienzo nuevos pueden producir diseños apretados o superpuestos incluso cuando el wireframe del cuerpo inline se ve bien. Si un mockup de lienzo se ve peor que la misma pantalla debajo del pliegue, asume que usó la ruta del kit heredado y reemplázala con una pantalla HTML.

Abrir e informar el recap

En el modo de privacidad de archivos locales, ejecuta plan local check primero, luego informa la URL del puente local desde npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind recap --open o desde <plan-dir>/.plan-url. Abre la UI del Plan alojado pero lee desde el puente de localhost en esta máquina, por lo que no se puede compartir entre máquinas. Si la aplicación Plan se está ejecutando localmente con el mismo PLAN_LOCAL_DIR, la ruta /local-plans/<slug> también es válida. No inventes una URL de base de datos alojada y no publiques solo para obtener un enlace absoluto del Plan.

Después de crear el recap, enlaza al revisor al plan renderizado con una URL absoluta en el origen cuya base de datos realmente contiene el plan. Ese origen es el servidor Plan MCP a través del cual acabas de crear el recap — NO cualquier servidor de desarrollo que sepas que está en ejecución. La herramienta de creación devuelve el enlace correcto; informa ESE. Nunca hagas que el enlace principal sea un archivo plan.mdx local, una carpeta local espejo o una ruta relativa como /plans/<id>.

Cuando el recap se publique en un PR para un repositorio privado, el plan l