Quality Check

Skill: Verificaciones automatizadas de calidad

Ejecuta la batería de checks automatizados que el stack exige (tipado, linter, unit tests, cobertura, build, e2e, sonar) más las suites de prueba que declare el estándar de testing del repo (integración, contrato, rendimiento…), adaptada al stack detectado, y emite un veredicto con su informe. Las únicas pruebas fijas son unit y cobertura —las dos únicas que se listan siempre, aunque salgan N/A—; el resto del conjunto sale de la config del propio repo (e2e) o del estándar de testing, y lo que no aplica no se lista — ver Suites de prueba.

Alcance: solo el plano automatizado. Este skill responde a «¿el código corre y cumple las reglas?». La pregunta «¿resuelve el problema correcto y está bien diseñado?» es del skill code-review (revisión cualitativa). Y «¿cada criterio de aceptación está probado?» es de trace-validate. Son tres skills independientes, cada uno con su veredicto e informe; quien los encadena es el orquestador de cierre (work-integrate, pr-create). Ver Relación con otros skills.

Audita, no arregla (por defecto). Aplica correcciones solo si el usuario lo autoriza explícitamente —o si .sdd-devkit/settings.json tiene verification.qualityCheck.confirmFix: "never" (ver Política de corrección)— y, tras corregir, vuelve a ejecutar. Fuera de un ciclo de implementación, entregar solo el informe es un resultado válido y frecuente con la política por defecto (always): se pregunta antes de tocar código (ver Corrección de fallos). No edita configuración, no instala dependencias ni hace commit/push/merge sin instrucción explícita. (Única excepción: dejar su propia caché ignorada en el .gitignore —añadiendo esa línea, y creando el archivo si no existiera—, ver Caché de corrida de pruebas.)

Proceso iterativo: toda corrección reinicia la corrida completa hasta un veredicto estable.

Sin cambios en el código no se repiten las pruebas. Si .sdd-devkit/test-run.json está fresco (mismo FINGERPRINT canónico), las suites y las validaciones de arquitectura se toman de ahí en cualquier modo, y solo se ejecutan los checks que la caché no cubre (tipado, linter, build, sonar). Solo no-cache o una petición explícita del usuario fuerzan la re-ejecución. Ver Caché de corrida de pruebas.

Entrada mínima: la raíz de un repositorio reconocible (ver references/stacks.md). Si no se detecta stack, parar y avisar. No se exige ningún artefacto del plugin: el repo puede no tener docs/specs/, ni US-XXX, ni convención de ramas — la corrida y el veredicto son idénticos. Ver Artefactos externos al plugin.

Alcance del informe

La corrida de este skill cubre todo el repositorio en el estado actual de la rama. Es inherente a lo que hace: tsc, el linter, la suite de pruebas y el build operan sobre el proyecto completo, y esa es justamente la señal que se busca. Una regresión provocada por el cambio en un archivo que nadie editó en esta rama solo aparece corriendo la batería entera.

Consecuencias prácticas:

• Un FAIL puede no venir del trabajo en curso. Un test que ya estaba roto antes de esta rama saldrá igual. No atribuirlo automáticamente al cambio reciente. Si la rama base es resoluble sin esfuerzo, se puede contrastar el archivo del fallo con git diff --name-only <base> (rango que incluye lo sin commitear) y anotar en el detalle del check que el fallo parece preexistente; si no lo es, no especular. En cualquier caso, la decisión de corregirlo aquí o sacarlo a un WI-XXX aparte es del usuario.
• No acotar la corrida a los archivos que cambiaron. Filtrar los tests por archivos tocados falsearía el resultado y anularía el valor de la puerta. Los modificadores (only <check>, no-tests…) acotan qué checks se ejecutan, nunca sobre qué parte del código; no existe forma de acotar el universo de archivos, y es deliberado.
• Excepción monorepo: si el repo tiene varios módulos, «todo el repositorio» significa todo el módulo elegido — la selección del módulo la resuelve el Paso 1 (ver references/stacks.md), preguntando si hay ambigüedad. No se auditan todos los módulos salvo petición explícita.
• El informe vive en docs/audits/, no en la carpeta de una US/WI, porque la corrida es de la rama consolidada y puede abarcar varios trabajos. (En modo tests-only no hay informe: el único artefacto es test-run.json.) Ver Caché de corrida de pruebas.

Mapa de referencias

Carga cada archivo solo cuando lo necesites (rutas relativas a la raíz del skill):

Referencias compartidas del plugin

Reglas transversales del catálogo; viven en la raíz del plugin, no en este skill.

• ${PLUGIN_ROOT}/reference/language.md: Idioma — resolución obligatoria del idioma de artefactos y mensajes. Lectura obligatoria antes de ejecutar el skill.
• ${PLUGIN_ROOT}/reference/asking.md: Preguntas — mecanismo estructurado, ritmo, fallback. Antes de la primera pregunta.
• ${PLUGIN_ROOT}/reference/artifacts.md: Artefactos — rutas del harness, identificadores, archivado. Al resolver una ruta o calcular un ID.
• ${PLUGIN_ROOT}/reference/verification.md: Política de corrección — si se pregunta antes de corregir un fallo o se corrige directo. Lectura obligatoria antes de ejecutar el skill.
• ${PLUGIN_ROOT}/reference/escalation.md: Límite de intentos — cuántos intentos consecutivos se hacen sobre un mismo problema que no se resuelve antes de escalar al usuario, y qué hacer al agotarlos. Lectura obligatoria antes de ejecutar el skill.

Cómo preguntar al usuario

Mecanismo, ritmo y fallback compartidos: ${PLUGIN_ROOT}/reference/asking.md.

Cada vez que este skill o sus referencias digan preguntar, pedir, confirmar, validar o sugerir algo al usuario, asume ese mecanismo; no se repite allí.

Excepción al ritmo: cuando aplica (ver Política de corrección), la pregunta señalada de este skill —si se corrigen los fallos o se entrega solo el informe— va después de presentar el reporte de lo que falló: el usuario decide con la información delante.

Política de corrección

Antes de ejecutar este skill, DEBES leer ${PLUGIN_ROOT}/reference/verification.md.

Las reglas de verification.md son obligatorias y determinan, vía verification.qualityCheck.confirmFix, si se pide confirmación antes de corregir un fallo (always, comportamiento por defecto) o si se corrige directamente sin preguntar (never). Ver Corrección de fallos.

No continúes hasta haber leído y aplicado verification.md.

Límite de intentos y escalamiento

Antes de ejecutar este skill, DEBES leer ${PLUGIN_ROOT}/reference/escalation.md.

Las reglas de escalation.md son obligatorias y determinan, vía escalation.maxAttempts y escalation.onLimit, cuántos intentos consecutivos se hacen sobre el mismo problema que no se resuelve —un check en FAIL o una prueba en rojo que sigue fallando tras aplicar la corrección— y qué se hace al agotarlos: detener el trabajo sobre ese problema, presentar el parte de bloqueo y preguntar al usuario cómo seguir (ask), o marcarlo como BLOCKED en el informe y continuar con el alcance que no dependa de él (report).

El contador es por problema, no global, y el límite es un techo, no una cuota: si no hay una hipótesis nueva que justifique el siguiente intento, se escala ya. Nunca se «resuelve» un bloqueo desactivando o saltando una prueba, relajando una aserción ni bajando un umbral.

No continúes hasta haber leído y aplicado escalation.md.

Vocabulario de veredictos y estados

Antes de redactar cualquier informe, DEBES leer ${PLUGIN_ROOT}/reference/verdicts.md.

Las reglas de verdicts.md son obligatorias: el valor canónico y el símbolo son estables, y la etiqueta que lee la persona se redacta siempre en el idioma resuelto por language.md. Ninguna etiqueta de este skill se fija en un idioma concreto.

No continúes hasta haber leído y aplicado verdicts.md.

Modelo de aplicabilidad y veredicto

Todo check pertenece a una de estas tres categorías (sin solape). Los nombres de la columna «Categoría» son valores canónicos: en el informe se escribe su etiqueta en el idioma resuelto.

SKIPPED vs N/A (definición tajante)

• N/A = el check no corresponde a este repo: ni aplica al stack, ni existe config/herramienta/script. No cuenta para el veredicto (se omite, o se marca con el símbolo — y su etiqueta).
• SKIPPED = el check sí correspondía (Bloqueante, o Condicional con config presente) pero no pudo ejecutarse porque la herramienta o la config está ausente o rota. Cuenta como INCOMPLETE.

Mnemónica: si el proyecto declara que algo debe correr y no corre → SKIPPED (INCOMPLETE); si nunca pidió ese check → N/A (irrelevante).

Veredicto

Precedencia: REJECTED > INCOMPLETE > APPROVED.

Estados de check

Los valores canónicos no se traducen; las etiquetas del informe sí se redactan en el idioma resuelto. PASS/FAIL/SKIPPED/PENDING/N/A, BLOCKING/CONDITIONAL/INFORMATIVE y APPROVED/REJECTED/INCOMPLETE son el vocabulario canónico de este documento, de stacks.md y —los cuatro primeros— del result de test-run.json. El informe lleva símbolo + etiqueta en el idioma resuelto, con la leyenda que los ata al inicio; ver ${PLUGIN_ROOT}/reference/verdicts.md y references/execution.md → Formato del informe. Ojo con el solape de símbolos: ✅ como estado de un check es PASS, mientras que ✅ en la línea Veredicto: es APPROVED, del informe entero.

Este veredicto cubre solo el plano automatizado. No lo mezcles con el de code-review ni con el de trace-validate: cada skill emite el suyo y el orquestador (work-integrate, pr-create) exige las tres puertas en aprobado antes de integrar o crear el PR. (Única salvedad: en un PR de promoción —develop → master—, pr-create solo exige esta puerta, porque cada trabajo ya pasó las tres al integrarse; ver pr-create.)

Ojo con el símbolo ⚠️ en el cierre: aquí (y en code-review) ⚠️ es INCOMPLETE y bloquea; en trace-validate y arch-audit es APPROVED_WITH_NOTES y no bloquea (se muestran las observaciones y se continúa). Mismo símbolo, efecto de compuerta opuesto — no asumir equivalencia al leer los tres informes juntos.

Catálogo de checks

Checks canónicos en orden de ejecución. La categoría real depende del stack — ver references/stacks.md.

El orden sigue la pirámide de tests (rápido → lento, dependencias antes que consumidores): estático (tipado/linter/arquitectura) → unit+coverage → suites configuradas → build → e2e → sonar. Las validaciones de arquitectura son análisis estático determinista —no tocan la red ni levantan servicios—, por eso van con el resto del estático y no con las suites de prueba. Una suite configurada que requiera el artefacto compilado (rendimiento, carga, accesibilidad sobre la app desplegada) se ejecuta después de build, junto a e2e. El fail-fast solo aplica al tipado, para evitar ruido en cascada. Justificación detallada en references/execution.md.

Cobertura sin tooling — no es un callejón sin salida. Si el repo no tiene ninguna herramienta ni configuración de cobertura, el check es N/A (el proyecto nunca lo pidió), no SKIPPED: aplica la mnemónica de SKIPPED vs N/A y el veredicto no queda condenado a INCOMPLETE de forma permanente. En ese caso, señalarlo en Próximas acciones como recomendación (configurar cobertura), sin bloquear. En cuanto exista config o herramienta, el check vuelve a ser Bloqueante y su ausencia de ejecución sí es SKIPPED.

Los checks deterministas alimentan la caché de test-run.json —las dos fijas (unit, coverage), más e2e y las suites configuradas cuando existen, más architecture cuando el repo tiene runner— ver Caché de corrida de pruebas. Sus consumidores son trace-validate (las suites de prueba; ignora architecture, que no es cobertura funcional) y arch-audit (solo architecture). Tipado, linter, build y sonar no producen entradas.

Suites de prueba: fijas y configuradas

El conjunto de pruebas de una corrida tiene dos partes, y solo la primera es fija:

De qué raíz sale el estándar de testing. Del módulo o repositorio que se está auditando, no siempre del principal: es la misma raíz que fija la Excepción monorepo del alcance. Si la corrida cubre un submódulo o un módulo de monorepo, el estándar que manda es su docs/standards/testing.md, y solo si ese no existe se cae al del repo principal. Es coherente con arch-manage, que escribe los estándares en la raíz del código que gobiernan (ver ${PLUGIN_ROOT}/reference/artifacts.md). Todas las menciones a docs/standards/testing.md de este skill se leen contra esa raíz.

Reglas:

• Lo que no aplica no se lista. La tabla del informe incluye solo los checks que se ejecutaron, más unit y coverage siempre. Cualquier otro check en N/A —sin stack/config detectable, o excluido por un modificador del usuario— se omite del informe: no lleva fila, y no se añade nota al pie ni sección que enumere lo omitido. Esto vale para e2e igual que para tipado, linter, build o sonar.
• El estándar es la única fuente de las suites configuradas (salvo e2e, que sale del catálogo de checks). Si el repo no tiene estándar de testing, o su estándar no declara más clases de prueba que las fijas, la corrida son solo unit, coverage y —si hay config— e2e. No se añade ninguna otra suite por haberla detectado en el repo.
• Solo cuentan los requisitos vigentes. Un requisito con **Estado:** Deprecated o Superseded no se ejecuta ni se lista: dejó de ser exigible.
• La categoría sale del enunciado normativo del requisito (RFC 2119, ver ${PLUGIN_ROOT}/reference/language.md): DEBE / MUST → Bloqueante; DEBERÍA / PUEDE (SHOULD / MAY) → Condicional. Si el enunciado no es claro, tratarla como Condicional y anotarlo en el detalle del check.
• El estándar puede endurecer un check, nunca ablandarlo. Si declara e2e con DEBE, e2e pasa de Condicional a Bloqueante (y, al estar declarado, un e2e que no se puede ejecutar es SKIPPED, no N/A, así que sí lleva fila). Lo que el stack exige como Bloqueante (unit, coverage) sigue siéndolo aunque el estándar calle o suavice.
• Suite declarada que no se puede ejecutar → SKIPPED (INCOMPLETE), no N/A: el estándar es precisamente la declaración de que ese check debe correr — es la mnemónica de SKIPPED vs N/A aplicada al pie de la letra.
• Suite presente en el repo pero no declarada en el estándar: no se ejecuta y no bloquea. Anotarla en Próximas acciones como recomendación de declararla en el estándar (vía arch-manage), igual que se hace con la cobertura sin tooling.
• El comando se resuelve como el de cualquier otro check: scripts/tareas del manifiesto según references/stacks.md, usando como pista lo que el propio requisito diga sobre herramienta y ubicación. Si no se resuelve con certeza, preguntar en vez de adivinar.

Del estándar se toma qué clases de prueba existen, no sus umbrales. Los criterios de cumplimiento CR-XXX del estándar (cobertura ≥ 80 %, flujos críticos con e2e…) los audita arch-audit, no este skill. Aquí el umbral de cobertura que decide PASS/FAIL sigue siendo el configurado en el tooling del repo. Que ambos números deban coincidir es asunto de arch-audit.

Detección de stack y resolución por stack

El detalle por ecosistema vive en references/stacks.md, que se carga solo durante el Paso 1:

1. Inspeccionar la raíz e identificar el ecosistema por manifiesto (package.json, pom.xml, build.gradle, pyproject.toml/requirements.txt, go.mod, Cargo.toml, *.sln/*.csproj, composer.json).
2. Una vez identificado el stack, abrir references/stacks.md y usar únicamente la categoría, el comando y el parseo de ese stack — no antes (no arrastres columnas que no aplican).
3. Leer el estándar de testing (docs/standards/testing.md o docs/standards/testing/README.md) para resolver las suites configuradas. Si no existe, la corrida son solo las dos suites fijas más e2e si el repo tiene config — no es un error ni hay que avisarlo. Ver Suites de prueba.
4. Monorepo ambiguo o stack no detectable: parar y preguntar.

Modificadores de invocación

Las claves de los modificadores son siempre en inglés (estándar). Si el usuario no especifica ninguno, asumir default. El usuario puede nombrarlos en español; mapéalos a la clave en inglés.

Todo check omitido por modificador del usuario es N/A, nunca SKIPPED: una omisión solicitada no convierte el veredicto en INCOMPLETE.

Flujo de ejecución (resumen)

Ninguna corrección se aplica sin autorización —explícita del usuario, o de antemano vía verification.qualityCheck.confirmFix: "never" (ver Política de corrección)—; tras corregir, verifica el arreglo y reinicia. El detalle paso a paso, el formato del informe, el manejo de errores y los anti-patterns están en references/execution.md — léelo al iniciar la ejecución.

1. Detectar entorno: identificar stack, cargar references/stacks.md, leer el estándar de testing para resolver las suites configuradas, resolver comandos, capturar metadata y calcular el fingerprint.
2. Ejecutar los checks secuencialmente según el catálogo.
3. Evaluar el resultado y el veredicto con la tabla de Veredicto. Si hay FAIL, mostrar el reporte y resolver si se corrige según verification.qualityCheck.confirmFix (ver Política de corrección): con always, preguntar qué hacer — dentro de una implementación la pregunta es si se corrige, fuera de una implementación ofrecer además la salida «solo el informe»; con never, corregir directo sin preguntar. Si corresponde corregir y la rama tiene un artefacto identificable (US-XXX, WI-XXX, FT-XXX/TC-XXX en rama test/, o un artefacto externo al plugin), la corrección se delega en work-implement; solo si no hay artefacto de ningún tipo se aplica aquí — ver Corrección de fallos.
4. Construir informe: rellenar assets/quality-check-template.md.
5. Registro y salida: escribir siempre el informe en docs/audits/quality-check.md y —solo si la corrida ejecutó el conjunto de pruebas completo (las dos fijas, e2e y todas las suites configuradas que apliquen)— la caché en .sdd-devkit/test-run.json (creando los directorios si no existen), más un resumen en el chat. Excepción tests-only: no hay informe ni veredicto; el único artefacto es test-run.json. No hacer commit/push/merge sin instrucción explícita.

Tras cualquier corrección, el código cambió: recalcular el fingerprint (Paso 1) antes de escribir la caché. Escribir un test-run.json con el fingerprint previo lo vuelve falso — afirmaría corresponder a un estado del código que ya no existe.

Corrección de fallos

Todo hallazgo que implique modificar código —un check en FAIL o una prueba en rojo— se propone, nunca se aplica por iniciativa propia. Antes de tocar nada hay que resolver dos cosas, en este orden:

1. ¿Se corrige o se entrega solo el informe?

Se resuelve primero por verification.qualityCheck.confirmFix (ver Política de corrección):

• never → corregir directo, sin preguntar, en cuanto haya un check en FAIL o una prueba en rojo. Saltar el resto de este punto y seguir con el punto 2.
• always (o sin settings.json, comportamiento por defecto) → depende del contexto de ejecución:

Con always, la pregunta va por la herramienta de preguntas estructuradas del cliente (opciones tappables); si el cliente no la expone, formularla en prosa con las opciones enumeradas. Reglas:

• Preguntar una sola vez por corrida, presentando antes el reporte completo de lo que falló, para que el usuario decida con la información delante.
• Si el usuario elige Solo el informe → construir el informe (Paso 4), emitir el veredicto que corresponda (REJECTED si hay FAIL) y terminar. No tocar código, no reiniciar la corrida, no insistir. Dejar en Próximas acciones qué habría que corregir.
• Si el usuario elige Corregir → seguir con el punto 2.
• El usuario puede acotar el alcance («corrige solo el linter, el test lo veo yo»): respetarlo y tratar el resto como solo informe.
• Una petición explícita del usuario gana, en cualquier sentido («corrige todo sin preguntar», «esta vez solo quiero el informe»): se respeta para esa corrida sin tocar settings.json.

2. ¿Quién aplica la corrección?

Solo si el usuario autorizó corregir. Depende de si hay un artefacto de trabajo en curso:

Cómo resolver el artefacto: del prefijo de rama + identificador y de la existencia de su carpeta con progress.md:

Buscar también en docs/archive/. Al cerrar un trabajo, work-integrate y pr-create pueden mover su carpeta a docs/archive/user-stories/ o docs/archive/work-items/. Si no está en la ruta activa, mirar ahí antes de concluir que «no hay artefacto» y dejar de delegar en work-implement — y nunca crear la carpeta en la ruta activa por no haberla encontrado. Este skill solo lee la carpeta (para resolver el artefacto y decidir si delega); no escribe nada dentro. Ver work-integrate/references/archive.md.

Cuándo se da. En el flujo normal el archivado ocurre después de esta puerta (work-integrate paso 11, ya en la rama base tras el merge; pr-create Paso 5), así que aquí el artefacto suele estar todavía en la ruta activa. Se lo encuentra archivado al repetir el cierre tras una corrección, o al correr quality-check sobre trabajo ya integrado — dos situaciones normales, no excepcionales.

Una rama test/ NO es una rama suelta. Nace en work-implement (references/test-cases.md, Paso 1) siempre asociada a un artefacto padre y con su progress.md, y work-integrate la trata como trabajo integrable de pleno derecho. Se resuelve con el mismo mecanismo que feature/ o fix/. Ahí el fallo típico es una prueba en rojo, y el skill que sabe escribir esa prueba es work-implement (tipos TC-XXX / FT-XXX) — delegar es especialmente importante en este caso, no la excepción.

Si no se resuelve un artefacto del plugin, comprobar antes si hay uno externo (ver Artefactos externos al plugin); solo si tampoco lo hay, no hay artefacto: no delegar ni inventarlo. Si hay ambigüedad (varios candidatos), preguntar al usuario antes de delegar. Esta es también la señal que distingue los dos contextos del punto 1.

Qué se le pasa a work-implement al delegar: el artefacto en curso (US-XXX / WI-XXX / FT-XXX / TC-XXX), el check que falló, el comando exacto, la salida de error relevante y los archivos implicados. La corrección se atribuye a ese artefacto y se anota en su progress.md como nota de retrabajo — salvo que el artefacto esté archivado, en cuyo caso la nota va en este informe y no se escribe dentro de docs/archive/ (ver la regla de artefacto archivado en work-implement); work-implement aplica su propio criterio en su Modo corrección — un modo acotado, sin ritmo por unidad y sin exigir Estado: Ready ni working tree limpio.

Aplica igual a fallos de pruebas (las dos fijas, e2e y cualquier suite configurada) que a fallos de tipado, linter o build: en ambos casos hay que escribir o ajustar código, que es justo lo que hace work-implement.

En ramas test/, no presuponer que el fallo está en la prueba. Una prueba en rojo ahí puede significar que la prueba está mal o que hay una discrepancia real entre el TC-XXX y el comportamiento del código. Esa decisión no la toma este skill: se delega en work-implement, que aplica su criterio para los tipos TC-XXX / FT-XXX (parar, presentar la evidencia y decidir con el usuario si se corrige producción, si se corrige la prueba, o si vuelve a test-define). Nunca relajar una aserción para forzar el verde.

Tras la delegación, este skill retoma el control: verifica que el arreglo funciona re-ejecutando el check o la prueba que fallaba y, solo si pasa, recalcula el fingerprint y reinicia la corrida completa (Paso 2). Si el arreglo no resuelve el fallo, seguir iterando antes de reiniciar — dentro del límite de escalation.maxAttempts sobre ese mismo fallo (ver Límite de intentos y escalamiento). Agotado el límite, no se hace un intento más: se escala con el parte de bloqueo.

Si work-implement devuelve «corrección no aplicada», la iteración se detiene ahí. Ese resultado significa que el arreglo excedía su alcance acotado, que hay una discrepancia de especificación, o que el fallo es preexistente — y viene con el motivo y el skill al que se escaló (work-plan / test-define). En ese caso: no reintentar la delegación sobre ese mismo fallo ni corregirlo aquí como sustituto. Construir el informe (Paso 4) recogiendo el motivo y el escalado en Próximas acciones, emitir REJECTED y terminar. El cierre queda bloqueado hasta que el escalado se resuelva — que es el resultado correcto, no un flujo incompleto.

Límites. La delegación no convierte a este skill en implementador: no decide el diseño de la corrección ni escribe código por su cuenta cuando delega. Y nunca delega sin la autorización resuelta en el punto 1 (explícita del usuario, o verification.qualityCheck.confirmFix: "never") — la delegación es cómo se corrige, no si se corrige.

Artefactos externos al plugin

Este skill no exige que el trabajo esté especificado con los artefactos del plugin. Su entrada mínima es la raíz de un repositorio reconocible: la batería de checks corre igual sobre un repo sin docs/specs/, sin US-XXX, sin progress.md y sin convención de ramas. La ausencia de artefacto no degrada el veredicto ni el informe — solo cambia a quién se atribuye una corrección.

Es el mismo contrato que ya aplican test-define y trace-validate: el artefacto puede ser una US/WI/FT del repo **o

…(truncated)