verification-before-completion

Descripción general de la skill verification-before-completion

Para qué sirve verification-before-completion

La skill verification-before-completion es un flujo estricto de comprobación final para esos momentos en los que estás a punto de decir que un trabajo está terminado, corregido, pasando checks o listo para revisión. Su función es simple: frenar afirmaciones de éxito sin respaldo y exigir evidencia reciente antes de hablar.

Resulta especialmente útil en programación asistida por IA, flujos con agentes, preparación de commits y handoff de PR. Si alguna vez has visto frases como “los tests deberían pasar”, “el bug está arreglado” o “la build se ve bien” sin haber ejecutado realmente el comando correcto, esta skill apunta justo a ese fallo.

Quién debería instalar esta skill

Los perfiles a los que mejor encaja incluyen:

• desarrolladores que usan agentes de IA para editar código
• revisores que quieren actualizaciones de estado más limpias y respaldadas por evidencia
• equipos cansados de mensajes de cierre optimistas pero no verificados
• cualquier persona que use patrones de Skill Validation donde importa más la prueba que la confianza

Si lo que buscas principalmente es generación de código, planificación o ayuda amplia para depurar, esto no sustituye a esas skills. La skill verification-before-completion es una barrera de seguridad, no un flujo completo de entrega.

El trabajo real que resuelve

El trabajo real no es “ejecutar tests”. Es:

1. identificar qué evidencia demostraría la afirmación
2. ejecutar ahora esa verificación exacta
3. leer la salida real
4. hacer solo la afirmación que esa evidencia permite sostener

Suena obvio, pero ahí es exactamente donde se rompen muchos flujos asistidos por IA. Esta skill convierte esa expectativa en una puerta obligatoria antes de usar lenguaje de cierre.

Qué hace diferente a esta skill

La diferencia clave está en su enfoque estrecho. verification-before-completion no intenta ser lista con todo tu repositorio. Hace cumplir una única regla de alto valor:

no hagas afirmaciones de finalización sin evidencia de verificación reciente

Eso la hace especialmente buena como skill de capa final. Frente a un prompt genérico de “sé cuidadoso y verifica”, esta es más fácil de activar de forma consistente porque ofrece una función de decisión repetible: identificar, ejecutar, leer, verificar y luego hablar.

Cuándo verification-before-completion encaja especialmente bien

Usa la skill verification-before-completion cuando estés a punto de decir cosas como:

• “los tests pasan”
• “el bug está corregido”
• “la build termina correctamente”
• “esto está listo para merge”
• “el linter está limpio”

Esas afirmaciones requieren evidencias distintas. La skill ayuda a evitar un error muy común: demostrar algo cercano y luego exagerar el resultado.

Cómo usar la skill verification-before-completion

Contexto de instalación de verification-before-completion

Instálala desde el repositorio obra/superpowers:

npx skills add https://github.com/obra/superpowers --skill verification-before-completion

Como esta skill está contenida en un único SKILL.md, adoptarla es ligero. No hay scripts auxiliares ni archivos de recursos extra que tengas que entender primero.

Lee primero este archivo

Empieza por:

• skills/verification-before-completion/SKILL.md

Ese archivo contiene todo el contrato de comportamiento. Como aquí la estructura de soporte del repositorio es mínima, leer primero SKILL.md basta para entender si la skill encaja con tu flujo de trabajo.

Qué información necesita de ti la skill

La skill verification-before-completion funciona mejor cuando le das tres cosas:

• la afirmación que estás a punto de hacer
• el comando que realmente la demostraría
• cualquier limitación del entorno que esté bloqueando la verificación

Ejemplos de entrada:

• “Quiero decir que la corrección funciona. El comando que lo demuestra es pytest tests/api/test_login.py -q.”
• “Quiero decir que la build pasa. La verificación esperada es npm run build.”
• “Creo que el lint está limpio, pero todavía no he ejecutado ruff check ..”

Sin una afirmación concreta y un comando concreto, la skill solo puede darte una advertencia genérica.

Convierte un objetivo difuso en un prompt útil

Prompt débil:

• “¿Puedo decir que esto está hecho?”

Prompt mejor:

• “Antes de afirmar que esto está completo, aplica la skill verification-before-completion. La afirmación es: ‘el bug de login está corregido’. El mejor comando para demostrarlo es pytest tests/auth/test_login_bug.py -q. Si eso no basta, dime qué verificación adicional hace falta.”

Por qué esto es mejor:

• nombra la afirmación
• propone una vía de prueba
• permite que la skill cuestione una verificación insuficiente

Cómo invocar la skill en la práctica

Usa verification-before-completion justo antes de cualquier mensaje de cierre, resumen de commit o nota de PR. Un flujo práctico sería:

1. terminar el cambio de código
2. decidir qué afirmación exacta quieres hacer
3. identificar el comando que demuestra esa afirmación
4. ejecutar de nuevo el comando completo
5. revisar la salida y el estado de salida
6. rebajar o matizar la afirmación si la evidencia es incompleta

Este orden importa. La skill aporta más valor justo en el punto en el que la gente tiende a resumir con demasiado optimismo.

Haz coincidir cada afirmación con la prueba correcta

Un beneficio práctico importante de la skill verification-before-completion es que evita desajustes entre prueba y afirmación.

Ejemplos:

• Afirmación: “Los tests pasan”
  Prueba: el comando completo de tests correspondiente, con cero fallos

• Afirmación: “El linter está limpio”
  Prueba: el comando del linter mostrando cero errores

• Afirmación: “La build termina correctamente”
  Prueba: el comando de build finalizando con éxito

• Afirmación: “El bug está corregido”
  Prueba: un paso de verificación que reproduzca la ruta original del fallo y que ahora pase

Que el linter pase no demuestra que la build funcione. Que un archivo haya cambiado no demuestra que un bug esté arreglado. Ahí es donde fallan muchas salidas flojas de agentes.

Qué se considera evidencia de verificación reciente

“Reciente” significa que el comando se ejecutó para este estado exacto del trabajo, no que lo recuerdas de un intento anterior. En la práctica, eso implica:

• no basarse en salida antigua de terminal
• no asumir que archivos sin cambios implican resultados sin cambios
• no inferir éxito a partir de señales cercanas
• no usar una verificación parcial para sostener una afirmación más amplia

Si cambiaste código después de la última ejecución, esa ejecución ya quedó obsoleta a efectos de cierre.

Qué hacer cuando no puedes ejecutar la verificación

A veces el entorno bloquea la ejecución: faltan dependencias, no hay credenciales, hay servicios no disponibles, el sistema operativo no es compatible o simplemente no hay tiempo. En ese caso, no hagas la afirmación más fuerte.

Usa en su lugar un lenguaje basado en evidencia:

• “Hice el cambio, pero no pude ejecutar npm test en este entorno.”
• “La corrección está implementada, pero la verificación de la build sigue sin confirmarse.”
• “Solo verifiqué el formato; no se ejecutaron los tests de integración completos.”

Eso sigue siendo un uso correcto de verification-before-completion, porque la skill trata de informar el estado con honestidad, no de forzar una certeza que no existe.

Patrón de prompt práctico para agentes

Un prompt reutilizable y sólido:

“Usa la skill verification-before-completion antes de cualquier afirmación de éxito. Para cada afirmación, identifica el comando que la demuestra, ejecútalo de nuevo si es posible, lee la salida completa y afirma solo lo que la evidencia confirme. Si la verificación está bloqueada, informa de la limitación en lugar de insinuar éxito.”

Esto funciona bien en instrucciones para agentes, asistentes de PR y flujos de generación de commits.

Mejor flujo para casos de uso de Skill Validation

Para verification-before-completion for Skill Validation, trata la skill como validador final, no como herramienta principal de trabajo. Una secuencia recomendable es:

1. usar otra skill para implementar o depurar
2. cambiar a verification-before-completion
3. verificar la afirmación concreta que quieres publicar
4. generar un resumen con evidencia del comando y del resultado

Esa separación mejora la confianza porque implementación y validación no quedan mezcladas.

Preguntas frecuentes sobre la skill verification-before-completion

¿verification-before-completion es solo un recordatorio para ejecutar tests?

No. La skill verification-before-completion es más estricta que un simple recordatorio. Obliga a relacionar cada afirmación con su prueba. La idea no es solo “ejecutar algo”, sino “ejecutar el comando que demuestra exactamente lo que estás a punto de afirmar”.

¿Esta skill es útil para principiantes?

Sí, especialmente para quienes todavía están aprendiendo qué demuestra realmente cada tipo de comprobación. Enseña un hábito muy valioso: no generalizar más allá de la evidencia disponible. Ese hábito mejora tanto la precisión técnica como la confianza de quienes revisan.

¿Cuándo no debería usar verification-before-completion?

No la uses como tu única skill para programar o depurar. No va a diseñar arquitectura, encontrar causas raíz ni escribirte un plan completo de tests. Es un checkpoint de cierre y funciona mejor acompañada de skills orientadas a la implementación.

¿En qué mejora a un prompt normal?

Un prompt normal suele decir “verifica antes de responder”, pero aun así los agentes derivan hacia afirmaciones blandas. La verification-before-completion skill es mejor cuando quieres una puerta consistente antes del cierre, con consecuencias explícitas para las afirmaciones sin respaldo.

¿Requiere un stack o toolchain concreto?

No. La skill es agnóstica al stack porque su lógica gira en torno a la evidencia, no al lenguaje o framework. Tú proporcionas el comando que demuestra el punto en tu entorno, ya sea pytest, npm test, go test, cargo test u otro verificador.

¿Puedo usarla cuando la verificación completa es demasiado costosa?

Sí, pero entonces tu afirmación también debe ajustarse. Si solo ejecutaste un test dirigido, di que pasó ese test dirigido. No lo eleves a “todo pasa” salvo que hayas ejecutado la prueba más amplia.

Cómo mejorar la skill verification-before-completion

Indica la afirmación antes de pedir validación

La mayor mejora en la calidad de salida consiste en escribir la frase exacta que te tienta poner. Por ejemplo:

• débil: “valida esto”
• fuerte: “Quiero decir: ‘el bug de pagos está corregido y los tests pasan’”

Eso ayuda a la skill a separar afirmaciones compuestas y a asignar una prueba a cada parte.

Nombra explícitamente el mejor comando de prueba

No obligues a la skill a adivinar las convenciones de tu repositorio si ya las conoces. Una entrada más sólida sería:

• “La comprobación canónica del proyecto es make test.”
• “El bug se demuestra con pytest tests/payments/test_refund.py -q más npm run build.”

Esto reduce la falsa confianza basada en comprobaciones incompletas.

Separa el estado de implementación del estado verificado

Un fallo habitual es mezclar “cambié el código” con “el problema está resuelto”. Mejora el uso de verification-before-completion usage pidiendo una respuesta en dos partes:

• qué cambió
• qué se verificó realmente

Eso mantiene los resúmenes honestos incluso cuando la ejecución está bloqueada.

Evita afirmaciones amplias a partir de checks estrechos

Si ejecutaste un único test focalizado, no le pidas a la skill que certifique todo el repositorio. Una formulación mejor sería:

• “¿Puedo decir que ahora pasa el test de regresión específico?”
• no “¿Puedo decir que el sistema está completamente arreglado?”

Este es uno de los hábitos de mayor valor que fomenta la skill.

Pide lenguaje alternativo cuando la evidencia sea parcial

Una forma práctica de mejorar la verification-before-completion guide en trabajo real es pedir redacción de respaldo:

• “Si la afirmación es demasiado fuerte para la evidencia, reescríbela en su versión más fuerte que siga siendo correcta.”

Eso convierte la skill en una herramienta de calidad comunicativa, no solo en un freno.

Vuelve a ejecutar tras cambios sustanciales

Si editas código después de una verificación exitosa, usa de nuevo la skill verification-before-completion. La evidencia reciente está ligada al estado actual, no al borrador anterior. Esto importa especialmente en bucles rápidos con agentes, donde un “pequeño ajuste final” puede invalidar comprobaciones previas.

Usa la evidencia en el resumen final

Para generar más confianza, incluye la prueba directamente en la nota de cierre:

• comando ejecutado
• resultado pass/fail
• cualquier límite u omisión

Ejemplo:

• “Verificado con pytest tests/auth/test_login_bug.py -q: correcto, 1 test, 0 fallos.”
• “No se verificó la suite completa de integración en este entorno.”

Ese estilo hace que la skill sea más valiosa para revisores y para tu yo futuro.

Vigila el patrón de fallo más común

El uso incorrecto más frecuente de verification-before-completion for Skill Validation es declarar éxito a partir de intención, cambios de código o expectativa, en lugar de salida real. Si quieres mejores resultados, hazte una última pregunta antes de cada mensaje de cierre:

“¿Qué salida de comando haría verdadera esta afirmación?”

Si no puedes responderlo con claridad, probablemente la afirmación todavía no está lista.