theus-cli-linux-x64 0.2.84

package/vendor/theus-arsenal/skills/flujo-git/SKILL.md

@@ -0,0 +1,714 @@
+---
+name: flujo-git
+description: Patrones de flujo de trabajo con Git, incluyendo estrategias de branching, convenciones de commits, merge vs rebase, resolución de conflictos y buenas prácticas de desarrollo colaborativo para equipos de cualquier tamaño.
+---
+
+# Patrones de flujo de trabajo con Git
+
+Buenas prácticas para el control de versiones con Git, estrategias de branching y desarrollo colaborativo.
+
+## Cuándo activar esta skill
+
+- Al configurar el flujo de trabajo de Git para un proyecto nuevo
+- Al decidir la estrategia de branching (GitFlow, trunk-based, GitHub flow)
+- Al escribir mensajes de commit y descripciones de PR
+- Al resolver conflictos de merge
+- Al gestionar releases y tags de versión
+- Al incorporar nuevos miembros del equipo a las prácticas de Git
+
+## Estrategias de branching
+
+### GitHub Flow (simple, recomendada para la mayoría)
+
+Ideal para despliegue continuo y equipos pequeños o medianos.
+
+```
+main (protegida, siempre desplegable)
+  │
+  ├── feature/user-auth      → PR → merge a main
+  ├── feature/payment-flow   → PR → merge a main
+  └── fix/login-bug          → PR → merge a main
+```
+
+**Reglas:**
+- `main` siempre está en estado desplegable
+- Crea ramas de feature desde `main`
+- Abre un Pull Request cuando esté listo para revisión
+- Tras la aprobación y el CI en verde, haz merge a `main`
+- Despliega inmediatamente después del merge
+
+### Trunk-Based Development (equipos de alta velocidad)
+
+Ideal para equipos con CI/CD sólido y feature flags.
+
+```
+main (trunk)
+  │
+  ├── feature de vida corta (1-2 días máximo)
+  ├── feature de vida corta
+  └── feature de vida corta
+```
+
+**Reglas:**
+- Todos hacen commit a `main` o a ramas de vida muy corta
+- Los feature flags ocultan el trabajo incompleto
+- El CI debe pasar antes del merge
+- Se despliega varias veces al día
+
+### GitFlow (complejo, orientado a ciclos de release)
+
+Ideal para releases programados y proyectos empresariales.
+
+```
+main (releases de producción)
+  │
+  └── develop (rama de integración)
+        │
+        ├── feature/user-auth
+        ├── feature/payment
+        │
+        ├── release/1.0.0    → merge a main y develop
+        │
+        └── hotfix/critical  → merge a main y develop
+```
+
+**Reglas:**
+- `main` contiene únicamente código listo para producción
+- `develop` es la rama de integración
+- Las ramas de feature salen de `develop` y vuelven a `develop`
+- Las ramas de release salen de `develop` y se fusionan en `main` y `develop`
+- Las ramas de hotfix salen de `main` y se fusionan tanto en `main` como en `develop`
+
+### Cuál usar en cada caso
+
+| Estrategia | Tamaño de equipo | Cadencia de releases | Ideal para |
+|------------|------------------|----------------------|------------|
+| GitHub Flow | Cualquiera | Continua | SaaS, apps web, startups |
+| Trunk-Based | 5+ con experiencia | Varias al día | Equipos de alta velocidad, feature flags |
+| GitFlow | 10+ | Programada | Empresas, industrias reguladas |
+
+## Mensajes de commit
+
+### Formato Conventional Commits
+
+```
+<tipo>(<ámbito>): <asunto>
+
+[cuerpo opcional]
+
+[pie(s) opcional(es)]
+```
+
+### Tipos
+
+| Tipo | Uso | Ejemplo |
+|------|-----|---------|
+| `feat` | Nueva funcionalidad | `feat(auth): add OAuth2 login` |
+| `fix` | Corrección de bug | `fix(api): handle null response in user endpoint` |
+| `docs` | Documentación | `docs(readme): update installation instructions` |
+| `style` | Formato, sin cambio de código | `style: fix indentation in login component` |
+| `refactor` | Refactorización de código | `refactor(db): extract connection pool to module` |
+| `test` | Añadir/actualizar tests | `test(auth): add unit tests for token validation` |
+| `chore` | Tareas de mantenimiento | `chore(deps): update dependencies` |
+| `perf` | Mejora de rendimiento | `perf(query): add index to users table` |
+| `ci` | Cambios de CI/CD | `ci: add PostgreSQL service to test workflow` |
+| `revert` | Revertir un commit anterior | `revert: revert "feat(auth): add OAuth2 login"` |
+
+### Ejemplos buenos vs malos
+
+```
+# MAL: vago, sin contexto
+git commit -m "fixed stuff"
+git commit -m "updates"
+git commit -m "WIP"
+
+# BIEN: claro, específico, explica el porqué
+git commit -m "fix(api): retry requests on 503 Service Unavailable
+
+The external API occasionally returns 503 errors during peak hours.
+Added exponential backoff retry logic with max 3 attempts.
+
+Closes #123"
+```
+
+### Plantilla de mensaje de commit
+
+Crea `.gitmessage` en la raíz del repo:
+
+```
+# <tipo>(<ámbito>): <asunto>
+# # Tipos: feat, fix, docs, style, refactor, test, chore, perf, ci, revert
+# Ámbito: api, ui, db, auth, etc.
+# Asunto: modo imperativo, sin punto final, máx. 50 caracteres
+#
+# [cuerpo opcional] - explica el porqué, no el qué
+# [pie opcional] - Breaking changes, closes #issue
+```
+
+Actívala con: `git config commit.template .gitmessage`
+
+## Merge vs Rebase
+
+### Merge (preserva el historial)
+
+```bash
+# Crea un commit de merge
+git checkout main
+git merge feature/user-auth
+
+# Resultado:
+# *   commit de merge
+# |\
+# | * commits de la feature
+# |/
+# * commits de main
+```
+
+**Úsalo cuando:**
+- Fusionas ramas de feature en `main`
+- Quieres preservar el historial exacto
+- Varias personas trabajaron en la rama
+- La rama ya fue pusheada y otros pueden haber basado trabajo en ella
+
+### Rebase (historial lineal)
+
+```bash
+# Reescribe los commits de la feature sobre la rama destino
+git checkout feature/user-auth
+git rebase main
+
+# Resultado:
+# * commits de la feature (reescritos)
+# * commits de main
+```
+
+**Úsalo cuando:**
+- Actualizas tu rama de feature local con el último `main`
+- Quieres un historial lineal y limpio
+- La rama es solo local (no se ha pusheado)
+- Eres la única persona trabajando en la rama
+
+### Flujo de rebase
+
+```bash
+# Actualizar la rama de feature con el último main (antes del PR)
+git checkout feature/user-auth
+git fetch origin
+git rebase origin/main
+
+# Corrige los conflictos que aparezcan
+# Los tests deben seguir pasando
+
+# Force push (solo si eres el único contribuyente)
+git push --force-with-lease origin feature/user-auth
+```
+
+### Cuándo NO hacer rebase
+
+```
+# NUNCA hagas rebase de ramas que:
+- Ya fueron pusheadas a un repositorio compartido
+- Otras personas han usado como base de su trabajo
+- Son ramas protegidas (main, develop)
+- Ya fueron fusionadas
+
+# Por qué: el rebase reescribe el historial y rompe el trabajo de los demás
+```
+
+## Flujo de Pull Requests
+
+### Formato del título del PR
+
+```
+<tipo>(<ámbito>): <descripción>
+
+Ejemplos:
+feat(auth): add SSO support for enterprise users
+fix(api): resolve race condition in order processing
+docs(api): add OpenAPI specification for v2 endpoints
+```
+
+### Plantilla de descripción de PR
+
+```markdown
+## Qué
+
+Descripción breve de lo que hace este PR.
+
+## Por qué
+
+Explica la motivación y el contexto.
+
+## Cómo
+
+Detalles de implementación clave que valga la pena destacar.
+
+## Pruebas
+
+- [ ] Tests unitarios añadidos/actualizados
+- [ ] Tests de integración añadidos/actualizados
+- [ ] Pruebas manuales realizadas
+
+## Capturas de pantalla (si aplica)
+
+Capturas de antes/después para cambios de UI.
+
+## Checklist
+
+- [ ] El código sigue las guías de estilo del proyecto
+- [ ] Auto-revisión completada
+- [ ] Comentarios añadidos en la lógica compleja
+- [ ] Documentación actualizada
+- [ ] No se introducen nuevos warnings
+- [ ] Los tests pasan en local
+- [ ] Issues relacionados enlazados
+
+Closes #123
+```
+
+### Checklist de revisión de código
+
+**Para quien revisa:**
+
+- [ ] ¿El código resuelve el problema planteado?
+- [ ] ¿Hay casos borde sin manejar?
+- [ ] ¿El código es legible y mantenible?
+- [ ] ¿Hay tests suficientes?
+- [ ] ¿Hay preocupaciones de seguridad?
+- [ ] ¿El historial de commits está limpio (con squash si hace falta)?
+
+**Para quien escribe:**
+
+- [ ] Auto-revisión completada antes de pedir revisión
+- [ ] El CI pasa (tests, lint, typecheck)
+- [ ] El tamaño del PR es razonable (idealmente <500 líneas)
+- [ ] Se limita a una sola feature/corrección
+- [ ] La descripción explica claramente el cambio
+
+## Resolución de conflictos
+
+### Identificar conflictos
+
+```bash
+# Comprobar conflictos antes del merge
+git checkout main
+git merge feature/user-auth --no-commit --no-ff
+
+# Si hay conflictos, Git mostrará:
+# CONFLICT (content): Merge conflict in src/auth/login.ts
+# Automatic merge failed; fix conflicts and then commit the result.
+```
+
+### Resolver conflictos
+
+```bash
+# Ver los archivos en conflicto
+git status
+
+# Ver los marcadores de conflicto en el archivo
+# <<<<<<< HEAD
+# contenido de main
+# =======
+# contenido de la rama de feature
+# >>>>>>> feature/user-auth
+
+# Opción 1: resolución manual
+# Edita el archivo, elimina los marcadores, conserva el contenido correcto
+
+# Opción 2: usar una herramienta de merge
+git mergetool
+
+# Opción 3: aceptar un lado completo
+git checkout --ours src/auth/login.ts    # Conservar la versión de main
+git checkout --theirs src/auth/login.ts  # Conservar la versión de la feature
+
+# Tras resolver, prepara y confirma
+git add src/auth/login.ts
+git commit
+```
+
+### Estrategias para prevenir conflictos
+
+```bash
+# 1. Mantén las ramas de feature pequeñas y de vida corta
+# 2. Haz rebase frecuente sobre main
+git checkout feature/user-auth
+git fetch origin
+git rebase origin/main
+
+# 3. Comunica al equipo cuando toques archivos compartidos
+# 4. Usa feature flags en lugar de ramas de larga vida
+# 5. Revisa y fusiona los PR con prontitud
+```
+
+## Gestión de ramas
+
+### Convenciones de nombres
+
+```
+# Ramas de feature
+feature/user-authentication
+feature/JIRA-123-payment-integration
+
+# Correcciones de bugs
+fix/login-redirect-loop
+fix/456-null-pointer-exception
+
+# Hotfixes (incidencias en producción)
+hotfix/critical-security-patch
+hotfix/database-connection-leak
+
+# Releases
+release/1.2.0
+release/2024-01-hotfix
+
+# Experimentos/POCs
+experiment/new-caching-strategy
+poc/graphql-migration
+```
+
+### Limpieza de ramas
+
+```bash
+# Eliminar ramas locales ya fusionadas
+git branch --merged main | grep -v "^\*\|main" | xargs -n 1 git branch -d
+
+# Eliminar referencias remotas de ramas ya borradas en el remoto
+git fetch -p
+
+# Eliminar una rama local
+git branch -d feature/user-auth  # Borrado seguro (solo si está fusionada)
+git branch -D feature/user-auth  # Borrado forzado
+
+# Eliminar una rama remota
+git push origin --delete feature/user-auth
+```
+
+### Flujo con stash
+
+```bash
+# Guardar trabajo en curso
+git stash push -m "WIP: user authentication"
+
+# Listar stashes
+git stash list
+
+# Aplicar el stash más reciente
+git stash pop
+
+# Aplicar un stash específico
+git stash apply stash@{2}
+
+# Descartar un stash
+git stash drop stash@{0}
+```
+
+## Gestión de releases
+
+### Versionado semántico
+
+```
+MAJOR.MINOR.PATCH
+
+MAJOR: cambios incompatibles (breaking changes)
+MINOR: nuevas funcionalidades, retrocompatibles
+PATCH: correcciones de bugs, retrocompatibles
+
+Ejemplos:
+1.0.0 → 1.0.1 (patch: corrección de bug)
+1.0.1 → 1.1.0 (minor: nueva funcionalidad)
+1.1.0 → 2.0.0 (major: breaking change)
+```
+
+### Crear releases
+
+```bash
+# Crear un tag anotado
+git tag -a v1.2.0 -m "Release v1.2.0
+
+Features:
+- Add user authentication
+- Implement password reset
+
+Fixes:
+- Resolve login redirect issue
+
+Breaking Changes:
+- None"
+
+# Enviar el tag al remoto
+git push origin v1.2.0
+
+# Listar tags
+git tag -l
+
+# Eliminar un tag
+git tag -d v1.2.0
+git push origin --delete v1.2.0
+```
+
+### Generación de changelog
+
+```bash
+# Generar changelog a partir de los commits
+git log v1.1.0..v1.2.0 --oneline --no-merges
+
+# O usar conventional-changelog
+npx conventional-changelog -i CHANGELOG.md -s
+```
+
+## Configuración de Git
+
+### Configuraciones esenciales
+
+```bash
+# Identidad del usuario
+git config --global user.name "Tu Nombre"
+git config --global user.email "tu@email.com"
+
+# Nombre de la rama por defecto
+git config --global init.defaultBranch main
+
+# Comportamiento de pull (rebase en lugar de merge)
+git config --global pull.rebase true
+
+# Comportamiento de push (solo la rama actual)
+git config --global push.default current
+
+# Autocorrección de errores tipográficos
+git config --global help.autocorrect 1
+
+# Mejor algoritmo de diff
+git config --global diff.algorithm histogram
+
+# Salida con colores
+git config --global color.ui auto
+```
+
+### Aliases útiles
+
+```bash
+# Añadir a ~/.gitconfig
+[alias]
+    co = checkout
+    br = branch
+    ci = commit
+    st = status
+    unstage = reset HEAD --
+    last = log -1 HEAD
+    visual = log --oneline --graph --all
+    amend = commit --amend --no-edit
+    wip = commit -m "WIP"
+    undo = reset --soft HEAD~1
+    contributors = shortlog -sn
+```
+
+### Patrones de gitignore
+
+```gitignore
+# Dependencias
+node_modules/
+vendor/
+
+# Salidas de build
+dist/
+build/
+*.o
+*.exe
+
+# Archivos de entorno
+.env
+.env.local
+.env.*.local
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Archivos del sistema operativo
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Cobertura de tests
+coverage/
+
+# Caché
+.cache/
+*.tsbuildinfo
+```
+
+## Flujos comunes
+
+### Empezar una nueva feature
+
+```bash
+# 1. Actualizar la rama main
+git checkout main
+git pull origin main
+
+# 2. Crear la rama de feature
+git checkout -b feature/user-auth
+
+# 3. Hacer cambios y commit
+git add .
+git commit -m "feat(auth): implement OAuth2 login"
+
+# 4. Enviar al remoto
+git push -u origin feature/user-auth
+
+# 5. Crear el Pull Request en GitHub/GitLab
+```
+
+### Actualizar un PR con nuevos cambios
+
+```bash
+# 1. Hacer cambios adicionales
+git add .
+git commit -m "feat(auth): add error handling"
+
+# 2. Enviar las actualizaciones
+git push origin feature/user-auth
+```
+
+### Sincronizar un fork con el upstream
+
+```bash
+# 1. Añadir el remoto upstream (una sola vez)
+git remote add upstream https://github.com/original/repo.git
+
+# 2. Traer los cambios del upstream
+git fetch upstream
+
+# 3. Fusionar upstream/main en tu main
+git checkout main
+git merge upstream/main
+
+# 4. Enviar a tu fork
+git push origin main
+```
+
+### Deshacer errores
+
+```bash
+# Deshacer el último commit (conservando los cambios)
+git reset --soft HEAD~1
+
+# Deshacer el último commit (descartando los cambios)
+git reset --hard HEAD~1
+
+# Deshacer el último commit ya pusheado al remoto
+git revert HEAD
+git push origin main
+
+# Deshacer cambios de un archivo específico
+git checkout HEAD -- path/to/file
+
+# Corregir el mensaje del último commit
+git commit --amend -m "Nuevo mensaje"
+
+# Añadir un archivo olvidado al último commit
+git add forgotten-file
+git commit --amend --no-edit
+```
+
+## Hooks de Git
+
+### Hook pre-commit
+
+```bash
+#!/bin/bash
+# .git/hooks/pre-commit
+
+# Ejecutar el linting
+npm run lint || exit 1
+
+# Ejecutar los tests
+npm test || exit 1
+
+# Buscar posibles secretos
+if git diff --cached | grep -E '(password|api_key|secret)'; then
+    echo "Posible secreto detectado. Commit abortado."
+    exit 1
+fi
+```
+
+### Hook pre-push
+
+```bash
+#!/bin/bash
+# .git/hooks/pre-push
+
+# Ejecutar la suite completa de tests
+npm run test:all || exit 1
+
+# Buscar sentencias console.log
+if git diff origin/main | grep -E 'console\.log'; then
+    echo "Elimina las sentencias console.log antes de hacer push."
+    exit 1
+fi
+```
+
+## Antipatrones
+
+```
+# MAL: hacer commit directamente a main
+git checkout main
+git commit -m "fix bug"
+
+# BIEN: usar ramas de feature y PRs
+
+# MAL: hacer commit de secretos
+git add .env  # Contiene claves de API
+
+# BIEN: añadirlos a .gitignore, usar variables de entorno
+
+# MAL: PRs gigantes (1000+ líneas)
+# BIEN: dividir en PRs más pequeños y enfocados
+
+# MAL: mensajes de commit tipo "update"
+git commit -m "update"
+git commit -m "fix"
+
+# BIEN: mensajes descriptivos
+git commit -m "fix(auth): resolve redirect loop after login"
+
+# MAL: reescribir historial público
+git push --force origin main
+
+# BIEN: usar revert en ramas públicas
+git revert HEAD
+
+# MAL: ramas de feature de larga vida (semanas/meses)
+# BIEN: ramas cortas (días), con rebase frecuente
+
+# MAL: hacer commit de archivos generados
+git add dist/
+git add node_modules/
+
+# BIEN: añadirlos a .gitignore
+```
+
+## Referencia rápida
+
+| Tarea | Comando |
+|-------|---------|
+| Crear rama | `git checkout -b feature/name` |
+| Cambiar de rama | `git checkout branch-name` |
+| Eliminar rama | `git branch -d branch-name` |
+| Fusionar rama | `git merge branch-name` |
+| Rebase de rama | `git rebase main` |
+| Ver historial | `git log --oneline --graph` |
+| Ver cambios | `git diff` |
+| Preparar cambios | `git add .` o `git add -p` |
+| Commit | `git commit -m "mensaje"` |
+| Push | `git push origin branch-name` |
+| Pull | `git pull origin branch-name` |
+| Stash | `git stash push -m "mensaje"` |
+| Deshacer último commit | `git reset --soft HEAD~1` |
+| Revertir commit | `git revert HEAD` |