daniloduuarte/verify-saas

Cuándo ejecutar (la regla que decide)

Ejecútalo con criterio, no por reflejo. Elige el nivel según la situación:

Situación	Qué ejecutar
Solo documentación, notas, comentarios, plan o especificación	Nada. Indica que no fue necesario.
Mitad del trabajo: entre ediciones, ronda de corrección, "¿habré roto los tipos?"	Rápido: node .claude/skills/verify-saas/driver.mjs --quick (o solo el comando de tipos, si solo cambió un tipo)
Fin de cada tarea o lote lógico, antes del commit	Completo, una vez
Antes de cualquier git push, deploy o merge en la rama principal	Completo, obligatorio. Si la última ejecución completa cubre exactamente el commit que va a subir, no la repitas.
Migración nueva, cambio en package.json, configuración de build, reglas de acceso/autenticación	Completo al final de ese cambio (riesgo de cambio estructural)
Después de git pull o merge del trabajo de otra persona	Completo (vuelve a anclar la línea base)

Nunca:

• ejecutar dos veces seguidas sin cambio intermedio;
• comenzar una segunda ejecución antes de leer la primera;
• ejecutar en paralelo con otro build o prueba en la misma carpeta;
• ejecutar el modo completo en medio de una ronda de ajustes en vivo (espera la solicitud de commit).

Siempre:

• confirmar que las pruebas apuntan a una base de datos/entorno de prueba, nunca producción (consulta el aviso en el README);
• releer tu propio diff antes de ejecutar: los imports sobrantes y nombres de propiedades incorrectos se detectan leyendo, no gastando una ronda;
• leer el informe completo, no solo el código de salida.

Cómo ejecutar

En la raíz del proyecto:

node .claude/skills/verify-saas/driver.mjs            # completo
node .claude/skills/verify-saas/driver.mjs --quick    # rápido, no toca la línea base
node .claude/skills/verify-saas/driver.mjs --baseline # recaptura el estado actual como "bueno"

Todo lo específico del proyecto (comandos, carpetas, palabras de alerta, etapas activadas o desactivadas) se guarda en verify-saas.config.json, en la raíz del proyecto. Sin ese archivo, se aplican los valores predeterminados para Next.js + TypeScript + npm.

Código de salida: 0 = nada empeoró; 1 = algo empeoró o algo ya estaba roto (tipos, build o pruebas).

Primer uso: adaptar al proyecto (para el agente que está leyendo esto)

Si el usuario acaba de instalar la skill y pidió adaptarla a su SaaS, haz lo siguiente en este orden:

1. Lee el proyecto (package.json o equivalente, carpetas de migraciones, cómo se ejecutan las pruebas) y ajusta verify-saas.config.json: comandos de tipos, lint, build y pruebas, structure.migrationsDir y alertKeywords. Desactiva ("enabled": false) lo que el proyecto no tenga.
2. Pregunta qué no puede dejar de funcionar en el negocio (agenda sin horario duplicado, stock sin volverse negativo, saldo que cuadre, empresa A sin ver la B, pago recibido dos veces acreditando una vez...). No inventes reglas: confírmalas con el usuario y escribe pruebas para ellas, usando docs/exemplos-por-nicho.md como modelo.
3. Confirma el entorno de pruebas. Nunca ejecutes pruebas contra producción. Si no hay base de datos o entorno de prueba, detente y avisa al usuario.
4. Solo entonces ejecuta node .claude/skills/verify-saas/driver.mjs --baseline y muestra el informe, señalando lo que ya estaba roto (deuda) y lo que pasó.
5. Informa al usuario qué se ajustó y que debe revisar las pruebas escritas.

Cómo leer el informe

En orden:

1. Tipos: pasó/falló y cantidad de errores respecto a la línea base.
2. Lint: comparado por huella digital (archivo:línea:columna:regla), no solo por el conteo. "5 errores antes, 5 después" puede ocultar 5 errores diferentes. La deuda antigua nunca es culpa tuya; solo cuentan los NUEVOS.
3. Build: pasó/falló y lista de rutas (si está configurado).
4. Pruebas: pasó/falló contra la línea base.
5. Estructura: dependencias nuevas, eliminadas o con versión cambiada; migraciones nuevas, marcadas con advertencia si contienen palabras de alerta (seguridad/permisos).

Símbolos: ✗ regresión (corregir), ✓ mejoró, = sin cambio, ℹ información, ⚠ verificar si fue intencional.

Después de imprimir, el modo completo sobrescribe la línea base con el estado actual. Por eso: corrige las regresiones antes de ejecutar de nuevo, de lo contrario la segunda ejecución tratará el error como "deuda antigua".

Buenas prácticas

• La línea base (verify-saas.baseline.json) debe committearse en el proyecto; es lo que hace que la comparación "desde la última vez" funcione entre sesiones y máquinas.
• Primera vez en el proyecto: ejecuta con --baseline en un estado que sepas que está bien.
• Las migraciones se comparan solo por el nombre del archivo. La skill no aplica ni valida el SQL; solo avisa que apareció una nueva y si toca seguridad.
• La skill no instala dependencias (npm install es una acción más grande de lo que una verificación debería hacer por sí sola).
• Si el informe muestra un problema "nuevo" que no causaste, revisa si alguien cambió el repositorio entre las ejecuciones (git log -3 --oneline).
• La protección real proviene de las pruebas que escribes (ver docs/exemplos-por-nicho.md). La skill solo garantiza que se ejecuten, y avisa cuando algo cambia.