CommunityProgramación y desarrollogithub.com

pr-tidy

Utiliza esta habilidad antes de abrir o actualizar una solicitud de extracción (pull request), después de una refactorización, cambio de diseño, renombrado o eliminación, o cuando te pidan ordenar, limpiar o barrer una rama. Encuentra lo que el diff dejó atrás: referencias obsoletas y redacción anticuada, nuevo comportamiento sin pruebas ni documentación, verificadores no conectados al validador o CI, o que pasan silenciosamente, números o ejemplos que ya no coinciden con su fuente, e información personal o credenciales a punto de ser confirmadas; corrige lo factual, marca el resto y reporta ambos con evidencia.

¿Qué es pr-tidy?

PR tidy es una habilidad para agentes de IA (como Claude Code, Cursor o Codex) que realiza una revisión de consistencia en una rama antes de convertirla en una solicitud de extracción. Analiza el diff de cambios y luego todo lo que ese diff debería haber cambiado también: referencias obsoletas a nombres, rutas o términos eliminados o renombrados; nuevo comportamiento que carece de pruebas o documentación; verificadores, linters o scripts de validación que no están conectados al CI o que pasan silenciosamente; números, versiones y ejemplos que ya no coinciden con su fuente; y credenciales o información personal a punto de ser confirmadas. La habilidad corrige automáticamente los problemas factuales y marca los que requieren decisión humana. Al final, genera un reporte detallado con evidencia de cada verificación. Está diseñada para trabajar con ramas locales contra la rama base del repositorio, buscando en todo el repositorio, no solo en los archivos modificados. Incluye reglas para no sobrescribir cambios no confirmados, no modificar archivos de otros equipos y respetar la estructura y terminología existente del proyecto.

Compatible con✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/chiuhoward/skills/tree/HEAD/pr-tidy

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

PR tidy

Un barrido de consistencia de una rama antes de que se convierta en una solicitud de extracción. Observa lo que el diff cambió, y luego todo lo que el diff también debería haber cambiado.

Trabaja sobre los cambios propios de la rama. Deja intacta la deuda no tocada en otras partes del repositorio a menos que el diff la haga incorrecta.

0. Alcance

  1. Lee primero las instrucciones del repositorio: AGENTS.md, CLAUDE.md, CONTRIBUTING*, README* y cualquier documento al que apunten.

  2. Encuentra la base y el diff:

    base=$(git merge-base origin/main HEAD)   # o la rama por defecto del repositorio
    git log --oneline "$base"..HEAD
    git diff --stat "$base"...HEAD
    git diff --name-only "$base"...HEAD
    
  3. Verifica el árbol de trabajo (git status). Conserva los cambios sin confirmar. Si una edición que harías se superpone con ellos, detente y pregunta.

  4. Si estás en la rama por defecto sin nada con qué comparar, detente y dilo.

1. Clasifica el diff

Ordena los cambios en:

  • Nuevo: archivos, comandos, funciones, opciones, banderas, claves de configuración, variables de entorno, scripts, habilidades.
  • Cambiado: comportamiento, valores predeterminados, APIs, firmas, reglas, y diseño: una guía o especificación que ahora dice algo diferente.
  • Eliminado o renombrado: cualquier cosa borrada, renombrada, movida o reemplazada.
  • Infraestructura: compilación, CI, pruebas, herramientas.

A partir de eso, enumera la superficie: cada nombre, ruta, bandera, opción, término y regla a los que un lector u otro archivo podría referirse. Para cambios de diseño, enumera también las frases clave de la idea antigua, no solo su nombre (una "verificación por nivel" eliminada aún podría describirse como "una verificación en cada nivel").

2. Referencias obsoletas

Para cada elemento eliminado, renombrado o rediseñado, busca en todo el repositorio, no solo en los archivos modificados:

git grep -n -w "nombre_antiguo"          # nombres, rutas, banderas
git grep -n -i "frase del diseño antiguo"

Busca en código, comentarios, pruebas, documentos, READMEs, ejemplos, cuadernos, plantillas, archivos de habilidades, diagramas (Mermaid y ASCII) y configuración. Cada coincidencia se actualiza o se marca con un motivo.

Luego construye un mapa de cobertura para cada elemento nuevo o cambiado: ¿dónde está documentado?

Mapa de cobertura:
  elemento         referencia   cómo-usar   ejemplo   explicación
  --nueva-bandera  README       -           -         -
  check_levels.py  scripts/     -           -         -

Un elemento sin cobertura es una brecha; repórtalo. No escribas páginas de documentación completas sin que te lo pidan.

3. Pruebas y documentación para comportamiento nuevo

Para cada comportamiento nuevo o cambiado:

  • Una prueba lo ejercita, en la capa que lo posee, y su ruta de fallo donde eso cambió. Prefiere el patrón de prueba existente del repositorio y la prueba más estrecha que detectaría la regresión.
  • La documentación lo describe dondequiera que se describía el comportamiento antiguo: referencia, ejemplos y cualquier guía que enseñara la forma antigua.
  • Reporta una prueba faltante solo cuando puedas nombrar el fallo concreto que detectaría. Omite especulaciones y deuda de cobertura no tocada.

4. Los verificadores fallan ruidosamente

Para cada verificador, linter, validador o script de verificación nuevo o cambiado:

  1. Conectado. Encuentra todos los puntos de entrada que usa el repositorio: .pre-commit-config.yaml, .github/workflows/*, Makefile, justfile, noxfile.py, tox.ini, pyproject.toml o scripts de package.json, y cualquier validador que llame a otras verificaciones. Confirma que el verificador se llama desde al menos uno. Si no, conéctalo de la misma manera que sus hermanos, o márcalo.
  2. Falla con entrada incorrecta. Ejecútalo con una entrada deliberadamente incorrecta; debe salir con código distinto de cero.
  3. Falla sin nada. Ejecútalo con entrada vacía o faltante (sin archivos, sin coincidencias, sin nada que analizar); debe salir con código distinto de cero o decir claramente que no verificó nada, nunca pasar silenciosamente.
  4. Tiene una prueba que cubre los puntos 2 y 3.

Para mantener esto cierto más adelante, agrega una prueba de conexión como references/test_checkers_wired.py.

5. Números, versiones y ejemplos

Enumera cada número, versión, fecha, URL, cita, comando y ejemplo de código en los archivos que el diff tocó o en los documentos que los describen. Para cada uno:

  • Nombra su fuente: el código o comando que lo produce, un valor de configuración, un conjunto de datos, o un artículo con su versión exacta (arXiv v3, un DOI).
  • Vuelve a verificarlo: vuelve a ejecutar el comando o vuelve a leer la fuente. Corrígelo, o márcalo si no puedes verificarlo.
  • Mantén su condición junto a él: el conjunto de datos, configuración, máquina o momento para el que un número es válido ("N puntos en T horas en la máquina M", no "N puntos").
  • Fija las fuentes externas a una versión.
  • Los números que seguirán cambiando es mejor generarlos desde el código (por ejemplo con cog, verificado por cog --check) que escribirlos a mano; sugiérelo.

6. Información personal y credenciales

Verifica todo lo que la rama agrega, y cada archivo no rastreado a punto de ser agregado, antes de que salga de la máquina. Esto es bloqueante: nada de lo siguiente se "arregla" siguiendo adelante.

git diff "$base"...HEAD          # confirmado en la rama
git diff; git diff --cached      # no confirmado aún
git status --short               # archivos no rastreados que podrían agregarse

Busca:

  • Credenciales: claves API, tokens, contraseñas, cadenas de conexión con contraseñas, claves privadas (-----BEGIN … PRIVATE KEY-----), secretos de la nube y del CI, cookies de sesión.
  • Archivos que las contienen: .env*, *.pem, *.key, id_rsa*, credentials*, secrets*, *.p12, JSON de cuentas de servicio, .npmrc o .pypirc con tokens, archivos de configuración local.
  • Información personal: direcciones de correo electrónico, números de teléfono, direcciones postales o físicas, nombres reales en ejemplos o datos de prueba, números de cuenta o ID, y datos identificativos de otras personas.
  • Detalles de la máquina: rutas absolutas al directorio personal (/Users/<nombre>, /home/<nombre>, C:\Users\<nombre>), nombres de host internos, direcciones IP privadas, nombres de usuario en registros o salidas de cuadernos.
  • Lugares ocultos: salidas y metadatos de cuadernos, registros, capturas de pantalla, fixtures, informes generados, mensajes de confirmación y el historial completo de la rama, no solo su estado final.

Ejecuta un escáner si el repositorio tiene uno (gitleaks, detect-secrets, pre-commit run --all-files), y lee el diff tú mismo también; los escáneres se pierden datos personales.

Cuando encuentres algo:

  • Nunca repitas el valor en el informe o en un mensaje de confirmación. Nombra el archivo, la línea y el tipo de elemento (clave AWS, dirección de correo electrónico).
  • No confirmado aún: elimínalo, muévelo a un archivo ignorado o a una variable de entorno, y agrega el patrón a .gitignore si es un archivo.
  • Ya confirmado en la rama: detente y dile al usuario. Una credencial que alguna vez se confirmó debe ser revocada y reemplazada, incluso después de reescribir el historial, porque ya podría haberse copiado. No reescribas el historial compartido sin el usuario.
  • Información personal que el usuario puso allí a propósito (su propio nombre público en una licencia, por ejemplo): pregunta, no elimines.

7. Corrige o marca

Edita mínimamente, con la propia voz, estructura y terminología del archivo. Lee un archivo completamente antes de editarlo.

Corrige sin preguntar:

  • correcciones factuales que se derivan directamente del diff;
  • nombres, rutas, conteos, versiones y referencias cruzadas obsoletas;
  • agregar un nuevo elemento a una tabla o lista existente;
  • conectar un verificador donde sus hermanos muestran el patrón.

Marca, o pregunta antes de cambiar:

  • texto narrativo, de diseño o de política, y cualquier cosa que contradiga la intención aparente de la rama;
  • eliminaciones y reescrituras grandes;
  • cambios sensibles a la seguridad;
  • entradas de CHANGELOG y aumentos de versión;
  • archivos que otra persona o equipo posee;
  • nuevas pruebas que necesitan una decisión de diseño.

Nunca: reescribas o regeneres entradas de changelog existentes, aumentes una versión silenciosamente, edites a mano archivos generados (usa su generador), o pegues secretos o credenciales reales.

8. Verifica con evidencia

Ninguna afirmación sin evidencia fresca de esta sesión, después de la última edición relevante:

  1. Nombra el comando que prueba la afirmación.
  2. Ejecútalo completamente.
  3. Lee toda la salida y el código de salida.
  4. Indica el resultado con esa evidencia, o indica el estado real.

Ejecuta lo que el repositorio ya tiene: sus pruebas, linters, pre-commit run --all-files, compilación de documentación y verificaciones de enlaces. Una herramienta que no está instalada o un servicio que está caído es una brecha de verificación, reportada como tal, nunca un pase. "Debería pasar" y un "hecho" del agente no son evidencia.

9. Informe

Alcance: <base>..HEAD, N archivos, M confirmaciones

Bloqueante
- ruta:línea — tipo de credencial o información personal (valor no mostrado), y lo que se necesita

Cambiado
- ruta:línea — qué cambió, y por qué el diff lo requería

Marcado (no corregido)
- ruta:línea — el problema, por qué no se corrigió, la corrección sugerida

Brechas de cobertura
- elemento — dónde debería documentarse o probarse

Verificado
- `comando` → resultado (código de salida)

No verificado
- qué, y por qué (herramienta faltante, servicio externo, necesita una decisión)

La capa mecánica

La mayor parte de las secciones 2 a 6 requiere juicio, pero algo de ello puede ejecutarse en cada confirmación. Para un repositorio que no lo tenga, ofrece la configuración inicial en references/pre-commit-config.yaml: higiene de archivos, ruff, codespell, detección de claves privadas y secretos (gitleaks), y pytest con diff-cover al empujar. Las verificaciones de enlaces lychee y el CI con puertas por ruta son mejores en un flujo de trabajo que en un hook de confirmación.

Créditos

Adaptado, con cambios, de habilidades con licencia MIT: docs-sync y review-test-coverage de Jakub Merta (jMerta/codex-skills); la clasificación de diff, el mapa de cobertura y las reglas de corregir-o-marcar de document-release de Garry Tan (garrytan/gstack); y la regla de evidencia de verification-before-completion de Jesse Vincent (obra/superpowers). Ideas, no texto, de los agentes pr-review-toolkit de Anthropic (anthropics/claude-plugins-official). Licencias: THIRD_PARTY_NOTICES.md.

Skills relacionados