name: hooks-automation-guardrails description: Definir hooks ligeros para automatizar validaciones repetitivas y proteger calidad en este repositorio. Usar cuando se quiera ejecutar checks automáticos antes o después de editar archivos, correr tests o preparar commits.

hooks-automation-guardrails

Cuándo sí usar hooks

• Cuando una validación se repite en casi cada cambio (formato, lint, chequeos de contratos).
• Cuando se quiere prevenir errores frecuentes antes de commit/push.
• Cuando el costo de automatizar es menor que revisar manualmente cada vez.

Cuándo no usar hooks

• Si el hook tarda demasiado y bloquea el flujo normal.
• Si depende de red o recursos inestables para cada ejecución local.
• Si duplica exactamente una validación ya ejecutada en CI sin aportar feedback temprano.

Hooks recomendados para este repo

1. Post-edición Python: correr check rápido de estilo en archivos tocados.
2. Pre-commit: validación mínima de tests unitarios focalizados por módulo afectado.
3. Pre-push: validar contratos OpenAPI/snapshots cuando se toquen api/, api/schemas/ o tests/integration/test_openapi_*.
4. Stop hook: recordar actualizar docs/ cuando cambien contratos públicos o flujos de release.

Política de diseño

• Mantener hooks pequeños, deterministas y opcionalmente desactivables por contexto.
• Priorizar feedback inmediato (segundos, no minutos).
• Versionar reglas y racional de cada hook dentro de la skill para evitar drift.

Estado de uso de hooks

• Hooks incluidos en esta skill: Post-edición Python, Pre-commit, Pre-push, Stop hook.
• Uso efectivo en este repositorio (al momento): documentados y recomendados, sin evidencia de activación automática versionada.