AkiGarage/readme-release-sync

Sincronización README-Versión (README Release Sync)

Usa este skill siempre que una tarea afecte al texto del README, notas de versión, changelogs, capturas de pantalla/GIFs del producto o documentación bilingüe.

El objetivo es reducir la carga de revisión del mantenedor: la documentación debe coincidir con el estado real del producto antes de que los revisores tengan que detectar nombres obsoletos, capturas, descripciones de funcionalidades o diferencias entre inglés y japonés.

Regla Principal

No edites la documentación dirigida al producto basándote únicamente en la documentación existente. Primero identifica la fuente de verdad actual: código de la aplicación, cadenas de la IU, capturas de pantalla/GIFs, rama de versión, archivos de versión, metadatos del paquete, o una captura/video reciente proporcionada por el usuario.

Flujo de Trabajo

1. Anclar el estado objetivo

   • Confirma el nombre del producto/aplicación, rama, versión, nombre del binario y alcance de la plataforma a partir de archivos del repositorio o instrucciones explícitas del usuario.
   • Inspecciona la implementación relevante o las cadenas de la IU para las funcionalidades que se están describiendo.
   • Trata las capturas/videos más recientes proporcionados por el usuario como evidencia visual autorizada, a menos que el código o el contexto de la rama contradigan claramente dicha evidencia.

2. Actualizar documentos y medios juntos

   • Reemplaza capturas de pantalla/GIFs obsoletos cuando la IU haya cambiado.
   • Verifica que cada referencia a una imagen exista y apunte al archivo previsto.
   • Comprueba que las capturas no contradigan visiblemente el nombre actual del producto, las etiquetas de menú, la versión o el estado de la IU.
   • Elimina referencias a medios antiguos cuando describan un comportamiento eliminado.
   • Para un lanzamiento público alimentado por un repositorio privado, actualiza los archivos README públicos en el repositorio público en la rama release/vX.Y.Z después de que la instantánea depurada se haya copiado allí. No uses el README privado como fuente de verdad final pública.
   • Trata el CHANGELOG público, los borradores de notas de versión, los documentos de instalación y los registros de desarrollo públicos como parte del mismo conjunto de documentos orientados a la versión. Deben usar los mismos nombres de producto, versión, nombres de activos, declaraciones de privacidad y redacción dirigida al usuario que el README.

3. Mantener los documentos bilingües equivalentes

   • Compara las secciones en inglés y japonés afirmación por afirmación.
   • Conserva los mismos hechos del producto, orden de funcionalidades, advertencias y requisitos de configuración en ambos idiomas.
   • No dejes comportamiento importante explicado en un solo idioma.

4. Redactar copia legible del README público

   • Haz que las secciones de primera lectura sean escaneables: párrafos cortos, una idea por párrafo y líneas en blanco donde mejoren la legibilidad.
   • Comienza con lo que hace el producto y lo que el usuario puede ver o hacer. Coloca los detalles de implementación más adelante, solo cuando sean relevantes para la configuración, la seguridad o la resolución de problemas.
   • Prefiere líneas de comportamiento claras en lugar de oraciones de funcionalidades empaquetadas. Una buena forma es una oración de resumen seguida de 2 a 4 líneas concisas de capacidades.
   • Para el comportamiento de la IU, describe el resultado visible: arrastrar para mover, redimensionar desde un borde o esquina, hacer doble clic para restablecer. Evita detalles internos del framework como zonas de impacto, rectángulos de cursor, internos de escalado o porcentajes predeterminados exactos a menos que el usuario los necesite.
   • Mantén la información detallada donde sea realmente útil, pero no hagas que el README público contenga explicaciones de implementación solo para mantenedores.
   • Aplica la misma regla de legibilidad a las notas de versión y entradas del changelog: evita precisión interna como porcentajes predeterminados exactos, redacción de zonas de impacto, mecánicas de rectángulos de cursor o detalles triviales del sistema de compilación, a menos que afecten a una corrección visible para el usuario, un paso de instalación o una ruta de solución de problemas.

5. Hacer que el texto sea fácil de leer para el público japonés

   • Prefiere términos comunes de la IU japonesa cuando sea natural: タブ, 詳細パネル, マウスオーバー, 最小表示, フローティングタブ.
   • Mantén los literales técnicos como comandos, rutas, nombres de paquetes, nombres de aplicaciones, URL e identificadores de código en inglés.
   • Elimina listas de funcionalidades redundantes y párrafos repetidos; haz que el conjunto principal de funcionalidades sea rápidamente escaneable para un lector japonés general.

6. Escanear en busca de desviaciones obsoletas

   • Nombres de producto antiguos, nombres de aplicación antiguos, nombres de binario antiguos y nombres de repositorio antiguos.
   • Números de versión antiguos fuera de las entradas históricas del changelog.
   • Etiquetas de IU obsoletas, notas de plataforma eliminadas y capturas de pantalla de comportamientos anteriores.
   • Afirmaciones que impliquen que una dependencia debe estar en ejecución cuando solo se requiere una CLI instalada o un paquete.

7. Validar antes de cerrar

   • Ejecuta los comandos de lint/verificación de documentos disponibles cuando sea posible.
   • Ejecuta un escaneo acotado con rg para nombres/versiones/etiquetas obsoletas.
   • Ejecuta el escaneo de redacción obsoleta/privada/demasiado interna en los archivos README, changelogs, notas de versión y cualquier documento público que se distribuya en la versión, no solo el README de nivel superior.
   • Verifica que los enlaces a imágenes del README existan.
   • Para PRs de versión, proporciona a los mantenedores las URL del README renderizado en GitHub para la rama/PR y espera la aprobación visual explícita. Esto debe coincidir con la visualización de GitHub que los usuarios verán realmente; las previsualizaciones locales, Markdown sin procesar, capturas de pantalla estáticas o comprobaciones automatizadas son solo evidencia de apoyo.
   • Inspecciona el git diff del repositorio público para que las afirmaciones del README, los metadatos de versión, los nombres de activos de la versión y los cambios de implementación copiados estén de acuerdo.
   • Para lanzamientos públicos, prefiere la rama release/vX.Y.Z -> PR -> CI -> fusión antes de la etiqueta o la creación de la GitHub Release. Los envíos directos a main deben usarse solo cuando el mantenedor solicite explícitamente omitir la puerta del PR.
   • Si el código cambió, ejecuta las pruebas o compilaciones relevantes.
   • Resume las comprobaciones de la fuente de verdad, no solo los archivos editados.

Lista de Verificación de Salida

Antes de finalizar, informa:

• nombre del producto/versión/rama verificados;
• referencias de medios verificadas;
• paridad japonés/inglés verificada;
• aprobación visual del README renderizado en GitHub recibida, o explícitamente pendiente aún;
• resultado del escaneo de redacción obsoleta;
• pruebas/compilación/verificaciones de documentos ejecutadas, o por qué no se ejecutaron.