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
-
Lee primero las instrucciones del repositorio:
AGENTS.md,CLAUDE.md,CONTRIBUTING*,README*y cualquier documento al que apunten. -
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 -
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. -
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:
- Conectado. Encuentra todos los puntos de entrada que usa el repositorio:
.pre-commit-config.yaml,.github/workflows/*,Makefile,justfile,noxfile.py,tox.ini,pyproject.tomlo scripts depackage.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. - Falla con entrada incorrecta. Ejecútalo con una entrada deliberadamente incorrecta; debe salir con código distinto de cero.
- 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.
- 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 porcog --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,.npmrco.pypirccon 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
.gitignoresi 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
CHANGELOGy 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:
- Nombra el comando que prueba la afirmación.
- Ejecútalo completamente.
- Lee toda la salida y el código de salida.
- 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.