Decisiones de diseño: fusión de convención de commits y PRs

Este documento registra las decisiones tomadas al fusionar tres fuentes (la propuesta de Jorge, el doc original “Convención de PRs y Commits” del rancho, y las skills que ya existían) en la versión final que quedó en /guides/convencion-pr-commits y en las skills de skills/. Se separa de las skills a propósito: las skills describen qué hacer, este documento explica por qué quedó así, para que se pueda revisar o revertir una decisión sin tocar el archivo operativo.

Commits

Formato de header: se tomó el de Jorge, <type>(<ticket>): <scope> <description>, con el ticket obligatorio en el header en vez de un footer Refs: (que tenía la skill original y el doc del rancho). Razón: hace el ticket grepeable de un vistazo sin tener que abrir el commit completo, y es lo que Jorge ya usa.
infra / no-ticket como valores de ticket: confirmado con Jorge. Se mantiene esta flexibilidad del doc original del rancho, que Jorge no contemplaba, para no romper el flujo en cambios de infra/CI sin ticket Jira.
Scope = tenant/dominio, nunca módulo: se sigue la tabla de scopes de Jorge (incluye core y common, que la skill original no tenía). El módulo puntual (search, cmedia, otel…) que antes vivía en el scope de la skill original, ahora va como tag opcional entre corchetes al inicio de la descripción: <type>(<ticket>): <scope> [<modulo>] <description>. Esta sintaxis del tag es una propuesta nueva de esta fusión, no viene de ninguna de las tres fuentes originales; ya fue validada con Jorge.
Set de tipos extendido: se toma el set completo de Jorge (test, style, perf, ci, build, revert) sumando hotfix del doc del rancho, porque Jorge confirmó que se suma.
Refs: eliminado: al quedar el ticket obligatorio en el header, el footer queda redundante. Confirmado con Jorge, se saca del todo. Se mantiene únicamente BREAKING CHANGE: como footer opcional.
Enforcement: se adopta el esquema de Jorge (hook local commit-msg + validador en CI), más robusto que la “convención recomendada, no bloqueante” del doc original.
Tenants agregados: ar-vea y pe-metro se suman a la lista canónica de tokens pais-bandera, tanto para título de PR como para scope de commit.

Pull Requests

Pre-flight checks: se incorpora del ejemplo genérico (persona externa) la verificación de gh instalado, branch no directamente en main, existencia de commits contra main, PR existente para la misma branch (evita duplicados), y warning de cambios sin commitear. La skill original no validaba nada de esto.
Reviewer Notes: se agrega como sección nueva al template y a la skill, agrupando archivos tocados en “lógica de negocio / alto impacto” vs “config / mocks / migraciones / bajo riesgo”. No existía ni en la skill original ni en el template original.
Modo draft/ready explícito: se agrega el flag --draft (default) / --ready, que la skill original no contemplaba.
Output de éxito con próximos pasos: se agrega al final del flujo, tomado del ejemplo genérico.
Descartado del ejemplo genérico: la extracción de tipo desde type/slug en el nombre de branch, el título type(scope): description, y la lógica de base branch dev/main. No aplican: el título de PR del rancho ya tiene su propio formato (pais-bandera/ticket/tipo) y la base siempre es main.
Mapeo de servicios inlineado en la skill: la skill original dependía de /prod-release y /qa-release para el mapeo alias->repo, lo cual no es viable si la va a usar todo el equipo (no todos tienen esos comandos instalados). Se inlineó la tabla completa en skills/create-pr/SKILL.md, con instrucción explícita de preguntar si un alias no está listado, en vez de adivinar.
Ya no hay main-temp: la excepción de base branch para us-tfm en bff/customers/auth quedó obsoleta (ya no hay ningún repo en main-temp). Se sacó toda referencia; la base es siempre main.
Bloque “Schema / interface changes” en el checklist: se incorporó al template final (migración up/down, mocks regenerados, breaking changes explícitos), tomado del ejemplo genérico. Nota: esta fue una decisión tomada por default dado que el equipo trabaja constantemente con Go + gRPC + mocks + migraciones, pero no llegó a confirmarse explícitamente con una respuesta directa. Si al usarlo resulta que agranda demasiado el checklist para PRs chicos, se puede sacar sin tocar el resto del template.

Fuente de los templates de PR

Se agregó a la skill la instrucción de preferir el .github/PULL_REQUEST_TEMPLATE.md del repo (si existe) por sobre el template del vault, porque GitHub soporta templates de PR nativos por repo y los autocompleta al abrir un PR desde la UI, no solo vía esta skill. Ver para-agente/instrucciones-implementacion.md para el detalle de cómo distribuir el template a cada repo.