0x0w1/jig

README

Usa este skill para crear o actualizar el README.md del repositorio a partir del estado real del repositorio.

Procedimiento

1. Escanea el repositorio:
   • Archivos de manifiesto y compilación: pyproject.toml, package.json, Cargo.toml, go.mod, Makefile, archivos de bloqueo.
   • Puntos de entrada, definiciones de argumentos de CLI, scripts y configuraciones de servicio (Dockerfile, docker-compose*.yml).
   • Documentación existente en docs/ y ejemplos de uso en el código.
2. Clasifica el tipo de proyecto: herramienta CLI, librería, servicio/app u otro. El tipo selecciona el diseño de secciones a continuación cuando no hay perfil configurado.
3. Resuelve el perfil del README según el Contrato de Perfil a continuación. Un perfil que se resuelve reemplaza los valores predeterminados genéricos para este repositorio; cuando ninguno se resuelve, propón uno y continúa de cualquier manera.
4. Ramifica según el estado actual:
   • Sin README.md → ruta de creación: redacta el README con el diseño de secciones a continuación.
   • README.md existe → ruta de actualización: verifica cada afirmación verificable en el README — comandos, opciones, rutas de archivo, enlaces, declaraciones de características — contra el repositorio. Reúne las discrepancias en una lista de desviaciones, informa la lista y luego aplica las correcciones. Deja las secciones que aún sean precisas sin tocar.
5. Aplica las reglas de exactitud a cada línea escrita.
6. Ejecuta el pase de compresión según las Reglas de Compresión a continuación:
   • Ruta de creación: aplícalo mientras redactas. Aún no se publicó nada, por lo que no hay nada que proponer.
   • Ruta de actualización: recopila la duplicación y la exageración en una propuesta — nombra cada hecho, dónde se repite y qué doc de detalle lo contendría — luego pregunta antes de mover nada. Informa la propuesta incluso si el usuario la rechaza.
7. Fusiona el cambio:
   • Cuando el repositorio tiene el skill develop-task-flow (o el jig-develop-task-flow instalado), síguelo: una rama chore/<slug>, una fusión squash con un commit docs:, luego empuja a develop.
   • De lo contrario, propón un commit normal en la rama actual.

Contrato de Perfil

Dos repositorios que son el mismo tipo de proyecto aún escriben sus READMEs de manera diferente: uno mantiene un espejo traducido, otro mueve la instalación a una guía, un tercero tiene una convención de tabla que sus contribuyentes ya siguen. Esas son decisiones, no hechos que se puedan escanear en el repositorio, por lo que se registran una vez y se leen en cada ejecución posterior.

Resuelve el perfil en este orden:

1. Variable de entorno JIG_README_PROFILE.
2. git config --local --get jig.readmeProfile.
3. .jig/readme.md.

Cuando un perfil se resuelve, anula el Diseño de Secciones y las Reglas de Idioma a continuación para ese repositorio; cualquier cosa que no mencione vuelve a ellos. Léelo, síguelo y nómbralo en el informe.

Cuando ninguno se resuelve, redacta uno a partir del escaneo y propónlo: el tipo clasificado, el idioma en el que el repositorio ya escribe, si existe un espejo, el orden de secciones que implica el README actual y qué docs de detalle ya contienen el desbordamiento. Escribe .jig/readme.md solo después de que el usuario lo acepte. Si el usuario lo rechaza o no responde, continúa con los valores predeterminados genéricos y dilo — un perfil faltante es un estado normal, no un bloqueo.

El archivo solo registra decisiones. No lleva umbrales ni lista de verificación; la calidad del README sigue siendo un juicio que este skill toma con el repositorio frente a él.

# Perfil del README

> Base: <cómo se decidió esto>, <AAAA-MM-DD>

## Idiomas

Canónico: `README.md` (Inglés). Espejo: `README.ko.md` (Coreano), actualizado en la misma tarea.

## Secciones

Título y fila de enlaces, Qué Es Esto, Inicio Rápido, Skills, Documentación, Licencia.

## Docs de Detalle

Opciones de instalación → `docs/installation.md`. Roadmap y registros de diseño → `docs/roadmap.md`, enlazados solo desde el inicio de la documentación.

## Convenciones

Las tablas de identificadores mantienen las celdas de descripción en una cláusula. Los comandos para contribuyentes permanecen en un bloque `<details>`.

Los títulos de las secciones son el contrato; la prosa debajo de ellos es propia del repositorio. Un perfil escrito antes de que existieran estos títulos aún se lee correctamente si los usa.

Diseño de Secciones

Secciones requeridas, en orden:

1. Título más una descripción de una línea.
2. Introducción: qué hace el proyecto y por qué existe.
3. Instalación.
4. Uso.

Adiciones por tipo de proyecto:

• Herramienta CLI: una tabla de comandos y opciones.
• Librería: un resumen de la API con código de ejemplo.
• Servicio/app: cómo ejecutarlo (dev y prod) y las variables de entorno requeridas.

Opcionales: enlaces a documentación, licencia.

Reglas de Diseño

• Una tabla está bien para identificadores que la gente copia — nombres de skills, comandos, opciones, rutas. Lo que rompe ese nombre es la relación de ancho entre columnas: GitHub dimensiona las columnas por contenido, por lo que una columna de descripción varias veces más larga que la columna de identificadores comprime el identificador hasta que se parte en medio del nombre, y el lector ve un nombre que no existe.
• Mantén las celdas de descripción aproximadamente tan cortas como los identificadores, alrededor de una cláusula. Cuando las descripciones se alargan, recórtalas o mueve todo a una lista: - **nombre** — descripción.
• Se espera el ajuste de línea dentro de una descripción y no necesita trabajo.

Reglas de Compresión

Un README se lee antes de que el lector haya decidido usar el proyecto. Todo en él compite por esa atención, por lo que la longitud es un síntoma: un README largo es casi siempre un hecho escrito en varios lugares, no un proyecto con mucho que decir.

Mueve, no elimines. Cuando el mismo hecho aparece en más de un lugar, mantenlo en el lugar al que un lector llega primero y mueve el resto al doc de detalle que ya lo cubre, creando ese doc solo si ninguno existe. Nada se pierde; el README deja de repetirse. No hay un recuento de líneas a alcanzar — un README de librería con los ejemplos de API que realmente necesita no es demasiado largo, y un README corto que dice lo mismo dos veces sigue estando mal.

Comienza con lo que el lector obtiene. La introducción dice qué se vuelve más fácil, no qué características existen. graba un tráiler de lanzamiento clasificado en la fusión es una característica; dejas de reconstruir por qué una versión fue menor es lo que el lector obtiene. Ordena las afirmaciones por la solidez de la evidencia, la más sólida primero, y haz que la prosa circundante las enumere en ese mismo orden — un párrafo y sus viñetas no deben implicar prioridades diferentes.

Afirma solo lo que el repositorio pueda respaldar, y di cuándo se aplica. Una afirmación que el repositorio no pueda demostrar se omite, no se suaviza. Indica la condición bajo la cual aparece el valor, para que un lector fuera de esa condición pueda descartar el proyecto rápidamente en lugar de descubrirlo más tarde.

Corta lo que no se lee antes de instalar. Roadmaps, registros de diseño y notas de dirección son cosas que el proyecto guarda para sí mismo. Enlázalos desde el inicio de la documentación, no desde el README.

Dobla el material de contribuyentes. Los comandos de compilación, regeneración y validación sirven a personas que ya clonaron el repositorio. Ponlos en un bloque <details> o en un doc de contribución.

Fusiona bloques que difieren en un valor. Los bloques de comandos separados por plataforma o destino que varían solo en un argumento se convierten en un bloque con ese argumento nombrado.

Dale al lector una forma de pasar el inicio. Cuando el README tiene más de unas cuatro secciones, coloca una fila de enlaces de una línea debajo del título para que un lector que regresa salte directamente a la sección para la que vino.

Reglas de Exactitud

• Escribe solo comandos de instalación y ejecución verificados contra el repositorio: un script, manifiesto o archivo de bloqueo debe mostrarlos.
• Verifica que cada ruta de archivo enlazada exista.
• No describas características, insignias o integraciones que el repositorio no contenga.
• Cuando una afirmación no se pueda verificar, omítela e infórmalo.

Reglas de Seguridad

• .jig/readme.md se escribe solo después de que el usuario acepta la propuesta, y nunca como efecto secundario de una actualización ordinaria del README.
• Un .jig/readme.md existente nunca se sobrescribe sin confirmación explícita. Propón el cambio y nombra lo que reemplaza.
• No se toca nada más dentro de .jig/. version-rubric es dueño de .jig/versioning.md.
• Un README publicado nunca se reestructura silenciosamente; el pase de compresión propone y espera.
• Los cambios de usuario no relacionados se preservan.

Reglas de Idioma

• Un README existente mantiene su idioma.
• Un README nuevo se escribe en el idioma que el repositorio ya usa para sus documentos, con valor predeterminado al inglés, con términos técnicos entre acentos graves.
• Una solicitud explícita de idioma del usuario anula ambas.

Informe

• Tipo de proyecto y la ruta tomada (creación o actualización).
• Perfil del README: ruta y fuente, o propuesto y rechazado, o ninguno y ejecutándose con los valores predeterminados genéricos.
• En la ruta de actualización: la lista de desviaciones y lo que se corrigió.
• La propuesta de compresión: cada hecho repetido en más de un lugar, a dónde se movería y si el usuario la aceptó.
• Afirmaciones que no se pudieron verificar y se omitieron.