Gentle AI — Habilidad de Ramas y PRs

Gentle AI — Habilidad de Ramas y PR

Cuándo Usarla

Carga esta habilidad cuando necesites:

• Crear una rama para una nueva corrección o funcionalidad
• Abrir un pull request en Gentleman-Programming/gentle-ai
• Preparar cambios para revisión

Reglas Críticas

1. Cada PR DEBE enlazar un issue aprobado — Closes/Fixes/Resolves #<N> en el cuerpo del PR, y ese issue DEBE tener status:approved. Los PRs sin esto son rechazados automáticamente por CI.
2. Categorización ordinaria type:* — CI rechaza cero o múltiples etiquetas de tipo. Enrútalo a través del contrato de flujo de trabajo canónico de creación de issues: una instrucción humana directa actual vincula el objetivo/acción exacto, la capacidad del host de destino está verificada, y utiliza una sola mutación acotada y lectura de vuelta del host de destino; de lo contrario, espera sin mutación.
3. Etiquetas de política protegidas — Agregar o quitar status:approved o size:exception requiere autoridad de política verificada de un mantenedor del repositorio host de destino o un aprobador autorizado por el repositorio para el objetivo/acción exacto, más un actor autenticado con viewerPermission MAINTAIN o ADMIN en el host de destino. size:exception además requiere una justificación documentada de sobrepresupuesto.
4. Presupuesto de revisión de 400 líneas — mantén los PRs dentro de 400 líneas cambiadas (additions + deletions) o documenta la justificación requerida para una etiqueta size:exception.
5. Las verificaciones automatizadas deben pasar — consulta la tabla de Verificaciones Automatizadas a continuación.
6. Sin trailers Co-Authored-By — nunca agregues atribución de IA a los commits.
7. Sin push forzado a main/master — rama protegida.

Flujo de Trabajo

1. Confirma que el issue tiene status:approved
   gh issue view <N> --repo Gentleman-Programming/gentle-ai

2. Crea una rama desde main usando la convención de nombres a continuación

3. Implementa los cambios siguiendo las especificaciones y el diseño

4. Ejecuta las verificaciones localmente (formato + unitarias + E2E)

5. Confirma usando el formato Conventional Commits

6. Abre un PR referenciando el issue
   → Declara EXACTAMENTE UN resultado type:* en el cuerpo del PR
   → Usa el contrato de flujo de trabajo canónico de creación de issues antes de cualquier mutación de etiqueta del PR
   → Rellena el cuerpo del PR usando la plantilla

7. Todas las verificaciones automatizadas deben pasar antes de fusionar

---

Nomenclatura de Ramas

Los nombres de las ramas deben coincidir con este patrón:

^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$

Tipo	Ejemplo
feat/	feat/user-login
fix/	fix/duplicate-observation-insert
docs/	docs/api-reference-update
refactor/	refactor/extract-query-sanitizer
chore/	chore/bump-bubbletea-v0.26
style/	style/fix-linter-warnings
perf/	perf/optimize-catalog-loading
test/	test/add-pipeline-coverage
build/	build/update-goreleaser-config
ci/	ci/add-e2e-docker-job
revert/	revert/undo-model-picker-change

Reglas:

• Todo en minúsculas
• Usa guiones, puntos o guiones bajos como separadores (sin espacios, sin mayúsculas)
• La descripción debe ser corta y descriptiva

---

Formato del Cuerpo del PR

El cuerpo del PR debe seguir la plantilla en .github/PULL_REQUEST_TEMPLATE.md. Todas las secciones son obligatorias a menos que se marquen como opcionales.

## 🔗 Issue Vinculado

Closes #<N>

## 🏷️ Tipo de PR

- [ ] `type:bug` — Corrección de error (cambio no disruptivo que soluciona un problema)
- [ ] `type:feature` — Nueva funcionalidad (cambio no disruptivo que agrega funcionalidad)
- [ ] `type:docs` — Solo documentación
- [ ] `type:refactor` — Refactorización de código (sin cambios funcionales)
- [ ] `type:chore` — Cambios de compilación, CI o herramientas
- [ ] `type:breaking-change` — Cambio disruptivo

## 📝 Resumen

<!-- Descripción clara de qué hace este PR y por qué. -->

## 📂 Cambios

| Archivo / Área | Qué Cambió |
|-------------|-------------|
| `path/to/file` | Breve descripción |

## 🧪 Plan de Pruebas

**Pruebas Unitarias**
\`\`\`bash
go test ./...
\`\`\`

**Formato Go**
\`\`\`bash
go run ./internal/gofmtcheck
\`\`\`

**Pruebas E2E** (requiere Docker)
\`\`\`bash
cd e2e && ./docker-test.sh
\`\`\`

- [ ] Pruebas unitarias pasan (`go test ./...`)
- [ ] Formato Go pasa (`go run ./internal/gofmtcheck`)
- [ ] Pruebas E2E pasan (`cd e2e && ./docker-test.sh`)
- [ ] Probado manualmente localmente

## ✅ Lista de Verificación del Contribuidor

- [ ] El PR está vinculado a un issue con `status:approved`
- [ ] El PR se mantiene dentro de 400 líneas cambiadas, o se documenta la justificación de `size:exception` y la autoridad de política verificada
- [ ] La lectura de vuelta de la API confirma exactamente una etiqueta `type:*` apropiada en este PR
- [ ] Pruebas unitarias pasan (`go test ./...`)
- [ ] Pruebas E2E pasan (`cd e2e && ./docker-test.sh`)
- [ ] He actualizado la documentación si es necesario
- [ ] Mis commits siguen el formato Conventional Commits
- [ ] Mis commits no incluyen trailers `Co-Authored-By`

---

Verificaciones Automatizadas

Estas verificaciones se ejecutan en cada PR y todas deben pasar antes de fusionar:

Verificación	Qué Verifica	Cómo Solucionarlo
Verificar Carga Cognitiva del PR	El PR se mantiene dentro de 400 líneas cambiadas (additions + deletions) o tiene size:exception	Divide el PR, o documenta la justificación de size:exception y verifica la autoridad de política antes de su acción canónica de flujo de trabajo
Verificar Referencia al Issue	El cuerpo del PR contiene Closes/Fixes/Resolves #N	Agrega Closes #<N> al cuerpo del PR
Verificar que el Issue tiene status:approved	El issue vinculado tiene la etiqueta requerida	Usa el contrato de flujo de trabajo canónico de creación de issues solo cuando una instrucción directa actual y la capacidad del host de destino autoricen la acción exacta; de lo contrario, espera
Verificar que el PR tiene Etiqueta type:*	Exactamente una etiqueta type:* está aplicada al PR	Usa el contrato de flujo de trabajo canónico de creación de issues solo cuando una instrucción directa actual y la capacidad del host de destino autoricen la acción exacta; de lo contrario, espera
Pruebas Unitarias	go test ./... pasa	Corrige las pruebas que fallan antes de enviar
Formato Go	go run ./internal/gofmtcheck pasa	Formatea los archivos Go mal formateados antes de enviar
Pruebas E2E	cd e2e && ./docker-test.sh pasa	Corrige los escenarios E2E que fallan antes de enviar

---

Conventional Commits

Los mensajes de commit deben coincidir con este patrón:

^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9\._-]+\))?!?: .+

Formato

<tipo>(<ámbito-opcional>)!: <descripción>

[cuerpo opcional]

[pie opcional]

Tipos Permitidos

Tipo	Propósito	Etiqueta del PR
feat	Nueva funcionalidad	type:feature
fix	Corrección de error	type:bug
docs	Solo documentación	type:docs
refactor	Cambio de código (sin cambio de comportamiento)	type:refactor
chore	Mantenimiento, dependencias, herramientas	type:chore
style	Formato, linting (sin cambio de lógica)	type:chore
perf	Mejora de rendimiento	type:feature
test	Agregar o actualizar pruebas	type:chore
build	Sistema de compilación o dependencias externas	type:chore
ci	Configuración de CI	type:chore
revert	Revierte un commit anterior	coincide con el tipo revertido

Cambios Disruptivos

Agrega ! después del tipo/ámbito:

feat(cli)!: renombrar la bandera --config a --config-file

BREAKING CHANGE: la bandera --config ha sido renombrada a --config-file.

Los cambios disruptivos se asignan a la etiqueta type:breaking-change.

Ejemplos

feat(tui): agregar barra de progreso a los pasos de instalación
fix(agent): corregir detección de Claude Code en macOS
docs: actualizar guía de contribución
chore(deps): actualizar bubbletea a v0.26
refactor(pipeline): extraer ejecutor de pasos
style: corregir advertencias de linter en el paquete de catálogo
perf(system): almacenar en caché el resultado de detección de SO
test(installer): agregar cobertura para la ejecución de pasos del catálogo
build: actualizar configuración de goreleaser para arm64
ci: dividir trabajos de pruebas unitarias y E2E
revert: deshacer rediseño del selector de modelos
feat(cli)!: cambiar ruta de configuración predeterminada

---

Comandos

Configuración

# Confirma que el issue está aprobado antes de comenzar
gh issue view <N> --repo Gentleman-Programming/gentle-ai

# Crea la rama
git checkout main && git pull
git checkout -b fix/<descripción-corta>

Pruebas Locales

# Pruebas unitarias
go test ./...

# Formato Go
go run ./internal/gofmtcheck

# Pruebas unitarias — paquete específico
go test ./internal/tui/...

# Pruebas unitarias — verbose
go test -v ./...

# Pruebas E2E (Docker debe estar en ejecución)
cd e2e && ./docker-test.sh

Abrir un PR

gh pr create \
  --repo Gentleman-Programming/gentle-ai \
  --title "fix(agent): corregir detección de Claude Code en Linux" \
  --body "$(cat <<'EOF'
## 🔗 Issue Vinculado

Closes #42

## 🏷️ Tipo de PR

- [x] \`type:bug\` — Corrección de error (cambio no disruptivo que soluciona un problema)

## 📝 Resumen

Corrige la detección del binario de Claude Code que falla en Linux cuando HOME no está configurado.

## 📂 Cambios

| Archivo / Área | Qué Cambió |
|-------------|-------------|
| \`internal/agents/claude.go\` | Se agregó respaldo de variable de entorno HOME |

## 🧪 Plan de Pruebas

- [x] Pruebas unitarias pasan (\`go test ./...\`)
- [x] Pruebas E2E pasan (\`cd e2e && ./docker-test.sh\`)
- [x] Probado manualmente localmente

## ✅ Lista de Verificación del Contribuidor

- [x] El PR está vinculado a un issue con \`status:approved\`
- [x] El PR se mantiene dentro de 400 líneas cambiadas, o se documenta la justificación de \`size:exception\` y la autoridad de política verificada
- [x] La lectura de vuelta de la API confirma exactamente una etiqueta \`type:*\` apropiada en este PR
- [x] Pruebas unitarias pasan (\`go test ./...\`)
- [x] Pruebas E2E pasan (\`cd e2e && ./docker-test.sh\`)
- [x] He actualizado la documentación si es necesario
- [x] Mis commits siguen el formato Conventional Commits
- [x] Mis commits no incluyen trailers \`Co-Authored-By\`
EOF
)"

Verificar Estado del PR

gh pr checks --repo Gentleman-Programming/gentle-ai <número-del-PR>
gh pr view --repo Gentleman-Programming/gentle-ai <número-del-PR>