repo_Claude/.claude/commands/git/push.md

version, updated, tags

version	updated	tags
2.0.0	2026-03-11	git workflow trunk-based integration

Command: git-push

Integra cambios a master y publica. Soporta ramas issue/* y quick/*.

Para el usuario

Cuándo usar este comando

Usar cuando hayas terminado de trabajar en una rama temporal (issue/* o quick/*) y quieras integrar los cambios a master y publicar al remoto.

Sintaxis

/git:push

No requiere argumentos. Detecta automáticamente la rama actual y maneja el flujo completo.

Ejemplos

Ejemplo 1: Desde rama issue

# Estando en issue/0013-hot-reload
/git:push

Crea commits atómicos, ejecuta tests, merge a master, push y limpia rama local.

Ejemplo 2: Desde master con cambios

# Estando en master con cambios pendientes
/git:push

Detecta cambios, crea automáticamente rama quick/<slug>, y ejecuta flujo completo.

Para Claude

Precondiciones

Verificar antes de ejecutar:

• Repositorio es un repo git válido
• Hay cambios para commitear O estamos en una rama temporal
• Tests del proyecto disponibles (si aplica)

Inputs

No requiere inputs del usuario. El comando detecta automáticamente:

• Rama actual (master, issue/, quick/)
• Cambios pendientes (staged, unstaged)
• Archivos modificados

Flujo obligatorio

1. Verificar rama actual y estado

git branch --show-current
git status --short

Caso A: Estamos en rama issue/* o quick/*

✓ Continuar directamente al paso 2.

Caso B: Estamos en master con cambios pendientes

Crear rama quick automáticamente antes de continuar:

1. Detectar contexto automáticamente:

git diff --name-only
git diff --name-only --cached

2. Analizar archivos para generar slug descriptivo:

   • Cambios en README.md → update-readme
   • Cambios en .claude/ → update-claude-config
   • Cambios en feature_flags.json → update-flags
   • Cambios en dev/issues/ → update-issues
   • Cambios en archivos de código → usar nombre del archivo principal
   • Cambios múltiples sin patrón claro → misc-updates

3. Crear rama quick automáticamente:

git checkout -b quick/<slug-generado>

4. Mostrar mensaje informativo:

✓ Creada rama automática: quick/<slug-generado>

Si estos cambios son parte de un issue, cancela (Ctrl+C) y usa:
  /factory:fix-issue <NNNN>

5. Continuar al paso 2.

IMPORTANTE:

• Por defecto siempre crear rama quick/
• Solo usar issue/ cuando se invoque desde /factory:fix-issue o el usuario indique explícitamente
• No inventar números de issue
• El objetivo es reducir fricción: si no sabes qué es, es un cambio quick

Caso C: Estamos en master sin cambios

✗ Error: No hay nada que publicar

STOP

2. Revisar cambios y crear commits por bloque

git status --short
git diff --stat
git diff

Analizar los cambios y agruparlos en bloques lógicos. Cada bloque debe tener la misma naturaleza/propósito.

Tipos de bloques comunes:

• Nuevas funcionalidades (feat)
• Correcciones de bugs (fix)
• Tests (test)
• Documentación (docs)
• Refactoring (refactor)
• Configuración/mantenimiento (chore)

Crear commits atómicos por bloque:

git add <archivos_del_bloque_1>
git commit -m "<tipo>: <resumen breve>" -m "<descripción larga en español explicando qué cambia, por qué se hizo, impacto esperado y alcance del bloque>"

git add <archivos_del_bloque_2>
git commit -m "<tipo>: <resumen breve>" -m "<descripción larga en español>"

Convención de tipos:

• feat: nueva funcionalidad
• fix: corrección de error
• refactor: cambio estructural sin cambio funcional
• docs: documentación
• chore: mantenimiento, config, deps
• test: tests nuevos o modificados

Reglas críticas de commits:

• No WIP: nunca commitear "wip", "tmp", "fix fix" ni código a medias
• No mezclar tipos: no combinar feat: + test: en un mismo commit
• No squash: los commits individuales se preservan en master via --no-ff
• No rebase interactivo: si los commits ya son limpios, no reescribir historia
• Descripción larga obligatoria: cada commit debe tener cuerpo explicativo en español

3. Ejecutar tests

{{include: run-tests}}

Obligatorio antes de mergear:

go test -tags goolm ./...

Casos:

• Tests pasan → ✓ Continuar al paso 4
• Tests fallan → ✗ STOP: corregir antes de continuar. No mergear código roto.
• No hay tests aplicables (solo docs/config) → ℹ Indicar al usuario y continuar al paso 4

4. Evaluar feature flags

Feature flags se usan cuando el issue es parte de una feature multi-issue o el cambio tiene riesgo y necesita poder desactivarse.

Feature flag ≠ WIP — un flag protege código terminado y testeado, no código a medias.

Si se modificó dev/feature_flags.json o cambios son parte de feature multi-fase:

1. Verificar que dev/feature_flags.json existe y está actualizado
2. Confirmar que el flag correspondiente tiene el estado correcto (enabled: true/false)
3. Incluir el archivo en el commit correspondiente (no crear commit separado solo para flags)

Si el issue es autocontenido (se completa en esta rama):

• No necesita flag
• ✓ Saltar este paso

5. Merge a master con --no-ff

{{include: git-merge-to-master}}

git checkout master
git pull --rebase
git merge --no-ff <rama> -m "merge: <rama> — <título breve>"

Formato del mensaje de merge:

• Título: merge: <rama> — <descripción corta>
• Cuerpo (opcional): resumen de lo que entra

Ejemplos:

merge: issue/0021-threads-default-config — habilitar threads en agentes
merge: quick/fix-typo-readme — corregir typo en README

Si hay conflictos durante el merge:

1. Resolver los conflictos manualmente
2. git add los archivos resueltos
3. git commit (sin -m, para mantener el mensaje de merge)

6. Push a remoto

git push

Si falla el push:

• Error "rejected - non-fast-forward" → alguien pusheó a master antes
• Solución: git pull --rebase && git push

7. Limpiar rama local

git branch -d <rama>

Si el branch delete falla:

• -d falla si la rama no está mergeada
• Usar -D solo si estás seguro que el merge se completó correctamente

Verificación final

git log --oneline -3
git branch --list

Informar al usuario:

✓ Rama `<rama>` integrada a master y publicada

Commits creados:
- <commit 1>
- <commit 2>
- merge: <rama>

Rama local eliminada.
Master actualizado y sincronizado con remoto.

Convenciones

• Commits atómicos: un commit = un cambio lógico completo
• Mensajes descriptivos: título corto + cuerpo explicativo en español
• No mezclar tipos: feat, fix, test, docs cada uno en su commit
• Tests obligatorios: siempre ejecutar antes de merge
• Merge --no-ff: preservar historia de la rama
• Push inmediato: integrar y publicar en un solo flujo

Troubleshooting

Error: "nothing to commit, working tree clean"

Causa: No hay cambios pendientes para commitear.

Solución: Si estás en una rama temporal y todos los cambios ya están commiteados, continúa con el merge. Si estás en master sin cambios, no hay nada que hacer.

Error: "Tests failing"

Causa: Los tests no pasan.

Solución:

1. Ver detalles de los tests fallidos:

go test -v -tags goolm ./...

2. Corregir el código que causa el fallo
3. Re-ejecutar tests hasta que pasen
4. Crear commit con el fix si es necesario
5. Continuar con el merge

Error: "merge conflict in "

Causa: El archivo tiene cambios en master que conflictúan con tu rama.

Solución:

1. Ver conflictos:

git status

2. Abrir archivo y resolver marcadores de conflicto:

<<<<<<< HEAD
código en master
=======
tu código
>>>>>>> rama

3. Editar y dejar solo la versión correcta

4. Stagear archivo resuelto:

git add <archivo>

5. Completar merge:

git commit

Error: "branch -d failed"

Causa: Git detecta que la rama no está completamente mergeada.

Solución:

1. Verificar si el merge se completó correctamente:

git log --oneline -5

2. Si el merge commit está presente, forzar eliminación:

git branch -D <rama>

3. Si el merge no se completó, volver atrás y resolver el problema.

Error: "rejected - non-fast-forward"

Causa: Alguien más pusheó cambios a master mientras trabajabas.

Solución:

git pull --rebase
git push

Si hay conflictos durante el rebase, resolverlos y continuar:

# Resolver conflictos
git add <archivos-resueltos>
git rebase --continue
git push

Advertencia: "Detached HEAD state"

Causa: No estás en ninguna rama.

Solución:

git checkout master
# O crear rama si tienes cambios importantes
git checkout -b quick/rescue-changes

Reglas críticas

• NO hacer commits WIP - cada commit debe ser atómico y completo
• NO mezclar tipos en un commit (feat + test en commits separados)
• NO saltear tests - si fallan, arreglar antes de merge
• NO hacer push --force a master nunca
• NO hacer squash - preservar commits individuales vía --no-ff
• SIEMPRE escribir descripción larga en español en cada commit
• SIEMPRE ejecutar tests antes de merge a master
• SIEMPRE usar --no-ff para el merge
• SIEMPRE limpiar rama local después del merge