verification-before-completion

Descripción general

¿Qué es la skill verification-before-completion?

La skill verification-before-completion define una regla de flujo de trabajo estricta para desarrolladores y agentes: nunca digas que el trabajo está hecho, que los tests pasan o que un bug está corregido a menos que acabes de ejecutar el comando de verificación relevante y hayas comprobado su salida. Su principio central es:

Siempre, evidencia antes que afirmaciones.

En la práctica, esto significa que antes de escribir "los tests están pasando", "el build está en verde" o "el bug está corregido", debes:

• Identificar el comando que respalda esa afirmación
• Ejecutarlo de nuevo (sin basarte en ejecuciones antiguas ni suposiciones)
• Leer la salida y el código de retorno
• Solo entonces declarar el resultado, respaldado por esa evidencia

¿Para quién es esta skill?

Usa la skill verification-before-completion si:

• Trabajas en bases de código donde con frecuencia se cuelan tests fallidos, builds rotos o correcciones no verificadas
• Depend es de agentes o herramientas automatizadas que podrían afirmar éxito sin ejecutar realmente las comprobaciones
• Quieres una práctica de tests y verificación disciplinada y repetible como parte de tu flujo de desarrollo

Es especialmente relevante para:

• Automatización de tests: garantizar que las suites de tests se ejecutan realmente y se interpretan correctamente
• Automatización de flujos de trabajo: exigir que los pasos de finalización incluyan siempre comandos de verificación
• Equipos que hacen code review, integración continua y entrega continua y quieren menos sorpresas después de marcar algo como "hecho".

¿Qué problema resuelve verification-before-completion?

Sin un sistema de protección, es fácil:

• Suponer que los tests pasarán porque el cambio es "pequeño"
• Afirmar que un bug está corregido tras editar código, sin volver a ejecutar el escenario que fallaba
• Confiar en un build anterior exitoso en lugar de recompilar después de los cambios

La skill verification-before-completion define lo que el repositorio llama una Iron Law:

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

Al adoptar esta skill, conviertes esa ley en una regla de flujo de trabajo concreta para ti, tu equipo o tus agentes. Esto reduce:

• Falsas afirmaciones de estado "en verde" en pull requests
• Regresiones ocultas que nunca se testearon
• Malentendidos entre desarrolladores, revisores y automatización

¿Cuándo encaja bien esta skill?

Elige verification-before-completion cuando:

• Ya dispones de comandos de test, lint o build y quieres asegurarte de que siempre se ejecutan
• Usas agentes o scripts para tareas de desarrollo y necesitas que sean estrictos con la verificación
• Te importa más la fiabilidad del estado reportado que ahorrar unos segundos en tu flujo de trabajo

Puede ser menos útil si:

• Tu proyecto aún no tiene comprobaciones automatizadas significativas (sin tests, sin lints, sin comandos de build)
• Estás haciendo trabajo exploratorio en el que todavía no estás listo para declarar estados "passing" o "fixed"
• Solo usas el repositorio como referencia conceptual, no como un flujo de trabajo obligatorio

En esos casos, igualmente puedes usar la skill como guía para diseñar tests y comprobaciones futuros.

Cómo usarla

Instalación y configuración

Para instalar la skill verification-before-completion mediante npx:

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

Tras la instalación:

1. Abre el directorio skills/verification-before-completion en el repositorio obra/superpowers.
2. Empieza por SKILL.md para ver la regla completa y su justificación.
3. Integra la regla en la documentación de tu propio proyecto, la configuración de tus agentes o tus pautas de desarrollo.

No necesitas copiar exactamente la estructura del repositorio. Úsala como referencia para describir y hacer cumplir la regla en tu entorno.

Flujo central: la Gate Function

La skill define una Gate Function que debe ejecutarse antes de cualquier declaración de finalización. En tu trabajo diario, aplícala así:

BEFORE claiming any status or expressing satisfaction:

1. IDENTIFY: What command proves this claim?
2. RUN: Execute the FULL command (fresh, complete)
3. READ: Full output, check exit code, count failures
4. VERIFY: Does output confirm the claim?
   - If NO: State actual status with evidence
   - If YES: State claim WITH evidence
5. ONLY THEN: Make the claim

Si te saltas cualquier paso, dejas de seguir verification-before-completion.

Ejemplos de comandos típicos:

• Tests: npm test, pytest, go test ./..., mvn test
• Lint: eslint ., flake8, golangci-lint run
• Build: npm run build, make, cargo build --release
• Verificación dirigida de bugs: el script, test o comprobación manual específica que reproduce el problema original

Ejemplo: uso de la skill en un flujo de desarrollo

Escenario: Has actualizado código y quieres afirmar "All tests pass".

Aplica verification-before-completion:

1. IDENTIFY el comando: por ejemplo, pytest.
2. RUN el comando después de tus cambios:

   pytest
   

3. READ la salida y comprueba que el código de retorno sea 0.
4. VERIFY:
   • Si fallan tests, no declares éxito. En su lugar, informa algo como: "Tests are failing: 3 tests failing in test_user_flow.py. See pytest output."
   • Si los tests pasan, puedes afirmar: "All tests pass (pytest, exit code 0)."
5. ONLY THEN marca la tarea como completada, haz push de los commits o abre una pull request.

Puedes aplicar este patrón a cualquier declaración de estado: builds, linters, formateo o corrección de bugs.

Integración con agentes y automatización

Si utilizas agentes o scripts que te ayudan con el desarrollo:

• Configúralos para que cualquier afirmación sobre tests, builds o correcciones vaya precedida de la ejecución de un comando concreto y un resumen de la salida.
• Exige que el agente haga referencia al comando que ejecutó y al resultado, por ejemplo:
  • "Ran npm test: exit code 0, 0 failing tests."
  • "Ran npm run build: exit code 1, build failed. Not claiming completion."

En revisiones o pipelines de CI, puedes tratar cualquier afirmación sin evidencia como incompleta según verification-before-completion.

Adaptación a tus herramientas y entorno

El repositorio no impone un lenguaje o framework concreto. Para adaptar la skill:

• Asocia cada afirmación habitual a un único comando inequívoco que la verifique.
• Documenta esas asociaciones en tu propio repositorio (por ejemplo, en CONTRIBUTING.md o WORKFLOW.md).
• Fomenta o exige que colaboradores y agentes siempre:
  • Ejecuten esos comandos antes de decir "done"
  • Peguen o resuman la salida relevante al hacer sus afirmaciones

Ejemplos de mapeos afirmación→comando:

• "Backend tests pass" → pytest backend/tests
• "Frontend builds successfully" → npm run build en frontend/
• "Go module is clean" → go test ./... y golangci-lint run

Preguntas frecuentes (FAQ)

¿Cuál es la regla principal de verification-before-completion?

La regla principal es la "Iron Law":

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

Si no acabas de ejecutar el comando de verificación relevante y revisar su salida, no puedes afirmar honestamente que has tenido éxito.

¿Qué cuenta como "verification evidence"?

La verification evidence es la salida reciente de un comando que prueba directamente tu afirmación, por ejemplo:

• Una ejecución de la suite de tests que muestre 0 fallos y código de salida 0
• Una ejecución de linter que no reporte errores y termine con éxito
• Un comando de build que finaliza correctamente (exit 0)
• Un script o test de reproducción de un bug que ahora pasa

Resultados antiguos, suposiciones o "debería funcionar" no cuentan como evidencia bajo esta skill.

¿Puedo basarme en ejecuciones de tests anteriores si nada ha cambiado?

Bajo verification-before-completion, la respuesta por defecto es no. La skill insiste en la verificación reciente antes de cada nueva declaración de finalización. Si quieres basarte en ejecuciones previas, deberías ser explícito y cuidadoso sobre las condiciones en las que eso es aceptable, y asumir que debilita la garantía.

¿Esta skill exige herramientas o lenguajes concretos?

No. La skill verification-before-completion es agnóstica en cuanto a herramientas. Funciona con cualquier stack donde puedas:

• Definir comandos que verifiquen el comportamiento (tests, linters, builds, scripts)
• Ejecutarlos bajo demanda
• Interpretar sus códigos de salida y salidas

Solo tienes que rellenar los comandos relevantes para tu proyecto y seguir los pasos de la Gate Function.

¿En qué se diferencia de simplemente "correr tests" de vez en cuando?

La diferencia está en la disciplina y la consistencia:

• Ejecutas el comando de verificación siempre antes de declarar que algo está terminado.
• Siempre lees la salida en lugar de asumir que ha ido bien.
• Tratas cualquier afirmación sin evidencia como inválida.

Esto convierte la ejecución de tests y builds en una puerta formal, no en un extra opcional.

¿Es adecuada verification-before-completion para testing manual?

Sí, siempre que puedas definir un procedimiento claro que actúe como un "comando" para la afirmación. Por ejemplo:

• Documentar un test manual paso a paso que reproduzca un bug
• Ejecutarlo después de tu cambio
• Registrar el resultado como evidencia

Sin embargo, la skill funciona mejor cuando la verificación está automatizada mediante scripts o frameworks de testing, de forma que los resultados sean repetibles y fáciles de reejecutar.

¿Dónde puedo ver la definición original de la skill?

La descripción oficial de la skill verification-before-completion está en el archivo SKILL.md del repositorio obra/superpowers:

• Repositorio: https://github.com/obra/superpowers
• Archivo de la skill: skills/verification-before-completion/SKILL.md

Consulta ese archivo para ver la redacción exacta del principio, la Iron Law, la Gate Function y ejemplos de errores comunes que debes evitar.