AGENTIC QA · WORKFLOW SKILL
QA manual por ticket dentro del sprint: Planning → Execution → Reporting, con gates humanos en cada checkpoint.
El mapa completo · índice del deck
Las 4 fases del camino principal se despachan como subagentes secuenciales: cada reporte alimenta el briefing del siguiente, y cada stage cierra con el verificador liviano. Este mapa es el índice: cada nodo tiene su slide.
Antes de empezar · el modo se pregunta
| Modo | Entra | Sale |
|---|---|---|
| single-issue · User Story | Un ID de Story en Ready For QA | ATS + ATP + ATR + QA comment · ticket transicionado a QA approved · TC outlines (native) o Tests agrupados en el ATS y ejecutados (xray). Sin STP ni par de sesión del sprint. |
| single-issue · Bug | Un ID de Bug con fix en staging | Decisión de triage → solo Code Review, o verificación completa con ATP + ATR (xray: 1 Test de repro en-sprint · native: sin TCs, difiere a Documentation) |
| sprint-wide | Un número de sprint N | Par de sesión sprint-<N>/ (plan.md + progress.md) · STP find-or-create y vivo en Jira · artefactos por issue · interrupción y resume |
La pregunta del modo, siempre
Session Start pregunta: todo el backlog de QA del sprint (sprint-wide) o un issue (single-issue)? Un número de sprint es una pista, no una respuesta. Solo se saltea cuando el primer token de los argumentos nombra el modo: /sprint-testing sprint-wide 12 · /sprint-testing single-issue UPEX-123. En sprint-wide llega una segunda pregunta: un ejecutor o una flota?
Alcance por JQL, misma cadencia
El sprint sale de una JQL con los work types coverable que declara el proyecto, intersectada con lo que la instancia tiene (un tipo ausente se saltea con una nota, nunca bloquea). Cada issue paga los mismos 4 despachos: Session Start → Planning → Execution → Reporting.
Gate 0 · corre ANTES que todo
Ley 1 · args-as-answers
«QA UPEX-123 on staging» ya responde env y alcance. Solo se preguntan los huecos, en un único checklist.
Ley 2 · probe, don't assume
Un MCP configurado sigue en RED hasta que responde de verdad. Se sondea cada capacidad antes de usarla.
| Capacidad | Sonda |
|---|---|
| Env alcanzable (REQUIRED) | curl -sI {{WEB_URL}} + API root: 2xx/3xx pasa; env muerto → STOP antes de escribir un solo plan |
| Credenciales + roles (REQUIRED) | .env por entorno · un token por rol vía bun run api:login |
| Jira + modalidad TMS (REQUIRED) | carga /acli · resuelve jira-xray vs jira-native · carga /xray-cli si aplica |
| Por superficie (según alcance) | OpenAPI MCP (solo schema) · DBHub MCP · Playwright · inbox que pueda recibir (magic-link) |
Framework aún genérico (URLs null) → STOP: correr antes /project-discovery → /test-framework-adaptation.
URL ad hoc (preview, hotfix)? WEB_URL_OVERRIDE / API_URL_OVERRIDE en test-session-memory.md: gana a project.yaml en todas las etapas y nunca se escribe ahí (Gotcha 15).
Phase 0 · nunca empieces a ciegas
Dos memorias, dos preguntas. progress.md decide «qué etapa sigue?» · test-session-memory.md lleva la modalidad TMS + contexto del ticket que cada subagente lee. Ambas se consultan al retomar. Las dos viven en .session/, nunca en la carpeta PBI: un re-sync del cache PBI destruiría el archivo.
Entrada universal · prepara la mesa
⏸ El gate del hand-off (S10). Escribe la Story Explanation en lenguaje llano y SE DETIENE: nada transiciona a In Test sin tu OK explícito. Carpeta PBI nueva por ticket, nunca reusada (S9); los [SYNC] jamás se escriben a mano (S14).
Planning (históricamente Stage 1) · de los ACs a un plan ejecutable
| Fase | Qué produce |
|---|---|
| 0 · Triage | Short-circuit solo con evidencia citada: el ATP pre-sprint publicado en Jira, los labels shift-left-* con menos de 30 días y los ACs sin cambios (salta fases 1-3; los labels solos corren el flujo completo) · veto · risk score · factibilidad de datos: Discover / Modify / Generate por AC |
| 1-2 · Análisis | Contexto de negocio + técnico · ambigüedades y gaps marcados NEEDS PO/DEV CONFIRMATION |
| 3 · ACs refinadas | Cada AC reescrita Given/When/Then con datos específicos |
| 4-5 · Test outlines | Derivación por técnica (1:N) · nombre Should <BEHAVIOR> <CONDITION> · edge cases + estrategia de datos |
| 6 · Trazabilidad | Orden Set-first (xray): ATS: {KEY}: {título} (Test Set → epic QA Test Artifacts, components de la Story) con TODOS los TCs → ATP: {KEY}: {título} (Test Plan → epic QA Master Test Plan, creado desde el field del shift-left) → ATR: {KEY}: Story Testing (Test Execution → epic QA Test Artifacts) SIEMPRE con Test Environment (active_env) · listas de Plan/Exec derivadas de la membership del ATS |
Antes de autorar. Consulta business-domain-context (bun run context:map business-domain-context) para que ACs, outlines y títulos usen los términos canónicos; un término nuevo se propone por el refresh de esa skill, nunca se edita el mapa a mano. Una decisión de arquitectura de test difícil de revertir sale del plan a un ADR en .context/ADR/ (S15).
Planning · la doctrina que gobierna el plan
Piso, no techo
Cobertura = conformidad-AC + riesgo más allá del AC (límites, errores, estados, anomalías). Nunca reportar «% de ACs verificados» como completitud.
1 : N por defecto
Cada AC no trivial explota en varios casos. Colapsar a uno exige justificación escrita trivially atomic.
Criterio ≠ caso
Un criterio es una afirmación de negocio; un caso es una exploración concreta de cómo se cumple o se rompe.
| Disparador en el AC | Técnica obligatoria |
|---|---|
| Cualquier input, siempre | Equivalence Partitioning · un caso por clase válida + inválida |
| Rango / límite / longitud / ventana de fecha | BVA · min−1 · min · min+1 … max−1 · max · max+1 · cero/vacío/null |
| Campo de estado / ciclo de vida | State-Transition · cada transición válida + cada inválida |
| 2+ condiciones que interactúan · 3+ factores | Decision Table · Pairwise (registrando la reducción) · charters de Error-Guessing |
Planning · la regla que define la forma del skill
| Modality jira-native | Modality jira-xray (bun xray) | |
|---|---|---|
| Planning | Solo outlines en el ATP (nombre + 1 línea). Sin issues Test: un Test nativo es documentación y espera al gate de Documentation. | Crea + ejecuta issues Test para los outlines, a detalle ejecutable, agrupados en el ATS (Test Set per-Story) y ejecutados vía un Test Execution: el Test ES la unidad de ejecución de Xray. |
| Execution | Corre los outlines + explora más allá; PASS/FAIL en la memoria de sesión. | Ejecuta los Tests + explora. Una sonda exploratoria se vuelve Test solo si halló un defecto o vale repetirla. |
| Documentation | Crea Tests solo para lo regression-worthy, tras el ROI. | Selecciona + promueve al Regression Test Plan (RTP) (el Test Plan long-lived del proyecto, contra el que /regression-testing escribe cada RTR) + Test Set, y los enriquece. |
Formato, una vez por batch
Manual o Gherkin? Se sugiere, tú eliges, aplica a todo el batch. En una flota lo declara el brief.
Manual en dos pasos
Xray Cloud descarta en silencio los steps inline: crear sin steps y agregarlos uno a uno.
El knob del proyecto
testing.tc_creation_stage: auto = esta tabla · sprint-testing = Tests en ambas · test-documentation = en ninguna.
Planning · la traza, antes de tocar un browser
Chequeo de tres aristas (Gotcha 9)
Link List en Story + ATP + ATR, o bun xray trace UPEX-123. Verifica Story↔ATS, membership completa, Story↔ATP y Story↔ATR, y que las listas coincidan con el ATS. Un TC directo a la Story es último recurso: solo si la instancia no tiene el work type Test Set.
Título canónico del Test
Si Planning crea el issue Test, el summary nace canónico: {US_ID}: TC#: should <resultado> [<conector> <condición>] [given <precondición>]. El # se asigna una vez y no se renumera; Documentation lo re-verifica al promover.
Única excepción declarada al ATP item: qa.methodology.gate_mode: light puede colapsarlo por sprint, escrito en el STP con su ítem de deuda (S2).
Planning y Reporting · estados en Jira
| Artefacto | Nace en | Planning lo deja en | Reporting lo cierra en |
|---|---|---|---|
| Test (TC) | draft | ready vía start_design → ready_to_run | lo mueve Documentation |
| ATP | planning | ready vía designed | completed vía complete |
| ATS | designing | sigue designing | close vía done |
| ATR | active | sigue active | close vía complete |
| STP (sprint-wide) | planning | ready al fijar el scope | completed al cierre del sprint |
Assignee = tú mismo, al crear (S19)
ATP, ATS, ATR y cada Test nacen con assignee. Xray rechaza editar la membership de un Test Plan que no es tuyo: un ATP sin dueño falla a mitad del flujo. Si el find-or-create devuelve uno ajeno, se pregunta; nunca se reasigna en silencio.
Slug sin mapear (S18)
Lista las transiciones vivas, propone la más parecida en una pregunta, dispara el id vivo si dices que sí y recomienda bun run jira:sync-workflows. Si eliges saltarla queda como N/A declarado; un salto silencioso, nunca.
Cada Test va con parent epic QA Test Repository; el ATR nace con su Test Environment.
Planning · rama Bug · triage antes que plan
| Veredicto | Disparadores |
|---|---|
| SKIP: solo Code Review | texto/label puro, CSS/visual, docs, config/infra, refactor sin cambio de comportamiento; Execution y Reporting colapsan al comentario + transición |
| REQUIRE: test completo | dinero/billing, integridad de datos, auth/autorización, integraciones externas, máquinas de estado, cálculos, sin importar el score |
Sin veto → risk score
Feature nueva +3 · datos dinámicos +3 · ACs explícitas +2 · user-facing +2 · esfuerzo >4h +2 · prioridad alta +1 · multi-componente +1 → 0-3 LOW (Code Review) · 4-7 MEDIUM (ATP completo) · 8+ HIGH (ATP + edges extendidos). El resultado se presenta al usuario.
Reglas del bug run
ATP + ATR de retest. jira-xray: 1 Test de repro creado en-sprint al verificar el fix (1:N si el scope lo justifica), ejecutado en la Execution ReTest:. jira-native: sin TCs en el sprint, difiere a Documentation, como siempre. Ejecuta: reproducir el original → verificar el fix → regresión en áreas adyacentes → DB si es de integridad. Regla de oro: si amerita regresión, Documentation termina con un Test persistente: reusar el de repro o crear uno.
Execution · primera acción obligatoria
Veredicto
PASS → continuar a la trifuerza · FAIL → STOP: blocker de nivel entorno, se reporta y no se explora nada.
Reachability ≠ smoke (S7)
El preflight preguntó «está levantado el env?»; el smoke pregunta «funciona la feature?». Ambos corren: saltarse el smoke produce bugs falso-positivo contra un entorno roto.
Execution · exploración por capas
playwright-cli: happy path + edges: vacío, largo máximo, 0/−1/MAX_INT, <script>, refresh a mitad de flujo, botón atrás. Screenshot en el estado FALLIDO, con ruta destino explícita a evidence/ (el outputDir no se toca).
Maniobra de 3 herramientas: OpenAPI MCP solo schema → bun run api:login → curl autenticado. Matriz de status: 200 happy · 400 campo faltante · 401 sin auth · 403 otro tenant · 409 duplicado.
DBHub MCP: filas persistidas, triggers (total == SUM de items), sondas de constraint FK/CHECK/UNIQUE envueltas en transacción + ROLLBACK.
Orden según la feature
UI-céntrica: UI→API→DB · API-first: API→DB→UI · data-céntrica: DB→API→UI. Un no-2xx en la UI te escala a la capa API; datos raros en pantalla te mandan a la DB.
Sonda RLS (multi-tenant)
Con A y B del mismo rol: A lista/lee/edita datos de B? Cualquier VULNERABLE = Critical y BLOQUEANTE: los bugs de autorización nunca afloran en el happy path.
Execution · pausa graduada
| Clase | Ejemplos | Acción |
|---|---|---|
| BLOCKING | smoke/env caído · corrupción de datos · explotable en seguridad (auth bypass, cross-tenant) | ⏸ pausa YA: se presenta el bug y se espera tu decisión; no se despacha la siguiente etapa |
| NON-BLOCKING | cosmético · gap menor de validación · edge en TC no crítico · default de framework por recalibrar | se registra, TC FAILED, y se terminan los TCs restantes: todo se lleva al cierre de Execution |
| TOOL FAILURE | cualquier herramienta rota a mitad del pase | STOP: estado parcial reportado, tú eliges retry / skip / abort |
Casos dependientes del tiempo
TTL, magic links, OTPs: elegir la opción más alta: TTL corto de test → clock-mock → defer explícito documentado. Nunca un «BLOCKED» a secas: al cierre cada TC está PASSED o FAILED solo si se observó en su entorno, o en NOT RUN con su razón (el defer escrito es la deferral de QA, con tarea de seguimiento).
Evidencia
Capturas, traces y logs bajo evidence/ del ticket (gitignored). Se captura el bug, no la navegación hacia él.
Execution · sesiones de browser y evidencia
Una sesión por ticket, un estado por rol
Sesión con nombre (-s=UPEX-123), en memoria. El login sale del estado del rol, .auth/<env>-<role>.json vía state-load, nunca tipeado en la exploración. Y ese estado solo lo produce el login real de la app: nada de service-role key, API de administración de usuarios, magic link generado en el servidor ni JWT armado a mano (browser-sessions.md §4). Dos roles = dos sesiones. Cada sesión se cierra antes del reporte y playwright-cli list lo prueba.
Agentic Pair Testing
La IA y tú en tu propio Chrome. Lo gobierna testing.browser.pair_mode en .agents/project.yaml: null pregunta una sola vez y guarda la respuesta · true es el modo por defecto · false usa sesiones dedicadas, y pair solo si lo pides, con una confirmación.
Destino explícito (Gotcha 8)
Nadie reapunta el outputDir de .playwright/cli.config.json: queda en el directorio de la herramienta. Cada captura lleva su ruta al evidence/ del ticket (a un .png el outputDir no le aplica igual), y la ruta se muestra en el chat apenas existe.
Bug visual o de posición
Superposición, desalineación, un eje corrido: antes de reportar se carga /bug-screenshot-annotation, que marca la captura (círculos, flechas, callouts) en local. El PNG anotado va primero como evidencia. Un hallazgo textual no lo necesita.
Reporting · el veredicto auditable
| Resultado | QA comment | Transición |
|---|---|---|
| Story PASSED | Template A | → QA approved (vía qa_sign_off) |
| Story FAILED (defecto confirmado) | Template B + reporte de bug | → blocked (+ issuelink is blocked by), o queda in_test con el bug linkeado |
| Bug VERIFIED | Template C | → closed (vía retest_passed) |
| Bug NOT FIXED | Template D | queda ready_for_qa, se etiqueta al dev |
ATR por modalidad
jira-xray: actualizar la descripción del Test Execution + status de cada Test Run. jira-native: custom field acceptance_test_results (o comentario fallback) → sync → releer. Sin snapshot de ATR no se reporta nada (S3).
Recalibración de severidad (§5.0)
FAIL de seguridad/auth que huele a default de framework (cookie flags, CSP/HSTS): hipótesis + un hecho de verificación + decisión humana → PASSED WITH ISSUES (GO-con-deuda), no un blocker.
Cuerpos rich-text (S6). Los cuerpos rich-text (ATP, ATR, descripción del Test) se escriben en Markdown, se convierten y validan con el conversor .agents/skills/acli/scripts/md-to-adf.ts, y lo que se publica es el ADF JSON resultante; por la vía CLI, acli nunca convierte Markdown solo.
Reporting · doctrina de defect management
La feature ya vive arriba de Staging (visible al usuario final).
Feature aún pre-release: la salida normal del sprint testing.
No es un AC roto: mejora o AC sub-especificada hallada probando más allá.
Tres ejes, nunca mezclados
parent = epic de proceso «QA Defect Management» (jamás un epic de producto) · issue link = la Story origen · components = módulo de producto afectado. qa_assignee = tú mismo, nunca sobrescribiendo un owner existente.
Severidad → prioridad (lookup)
critica→Highest · mayor→High · moderada→Medium · menor→Low · trivial→Lowest (slugs de .agents/jira-required.yaml; override con justificación). Título: <EPIC>: <COMPONENT>: <resumen>.
Disciplina. Repro reproducible + evidencia o no hay ticket (S12) · una capa por bug, nunca UI+API+DB mezclados (S8) · buscar duplicados primero · borrador completo a la vista y tu confirmación antes de crear nada.
Cada stage · el cierre que no se saltea
Las líneas comunes viven en artifact-lifecycle.md §5 y no se repiten por skill.
Cómo se responde
Cada línea es YES o N/A con su razón; una línea en blanco cuenta como falla. Un NO deja el stage en NEEDS REVISION y no se avanza. Liviano: responde con lo que ya hizo, con a lo sumo una lectura extra.
Footer de sesión, solo en el chat
Cada captura muestra su ruta apenas existe; al cierre, la lista consolidada (verificada en disco, anotaciones primero). Después el footer: skills, MCPs y CLIs usados, niveles de testing tocados con «none» explícito y Refinements proposed:. Nunca en un comentario de Jira ni en el ATR.
Modo sprint-wide · procesar el sprint entero
El estado que ve el equipo = el STP
La descripción lleva el plan estable (un escritor, read-first); los comentarios, el progreso append-only por issue cerrado. Si chocan con el ATR de una Story, manda el ATR.
Checkpoint por etapa (S11)
Tras cada subagente, el orquestador anota la etapa en progress.md.
Archive al cerrar
.session/… → .session/.archive/<fecha>-… + resumen a memoria persistente. Lo que queda es Jira: STP, ATP, ATR, bugs.
Sprint-wide · el segundo eje: ejecutores
| 1 ejecutor (default) | N ejecutores (fleet mode) | |
|---|---|---|
| single-issue | sin cambios: esta sesión corre el issue | no existe: un issue, un ejecutor |
| sprint-wide | sin cambios: esta sesión recorre la cola | esta sesión es el conductor; una sesión por issue de la ronda |
Conductor
Habla contigo, arma las rondas, siembra un brief.md por issue, acuña tokens y estados de browser. Único escritor del sprint: plan.md, progress.md, STP.
Worker
single-issue sobre su KEY. Lo reconoce el token fleet worker del prompt y su brief, no las env vars. Sin checkpoints, sin saltear preflight ni sondas MCP, hasta worker_done.
launch.txt, siempre
En .session/sprint-testing/sprint-<N>/: una línea autocontenida por issue, regenerado entero en cada ronda. Sin orquestador, abres N terminales y pegas una línea en cada una.
Rondas ≠ waves. Una wave es un bucket de estado de Jira (qué issues son elegibles); una ronda es cuántos corren a la vez, hasta orchestration.max_workers, que es un tope y nunca el interruptor. Si no hay orquestador disponible, la skill no lo nombra: ni en el plan, ni en el preflight, ni en el ATR.
Cómo lo invocas · tres hosts
El primer token decide
Si el primer argumento nombra un modo, ese es el modo; si no, Session Start pregunta. Abrí el host tal cual (claude, opencode, codex o su app): cada MCP lee .env por su cuenta.
Se lee en Session Start
.agents/project.yaml · catálogos Jira · mapas de contexto + MTP · el ticket vía jira:sync-issues. El .env no entra: la IA nunca lo abre.
El humano conserva los juicios
Modo · OK de la Story · triage · cada bug · retry/skip/abort.
quién decide qué · los tres stages de esta skill
| Stage | El agente hace | La persona firma | Autonomía |
|---|---|---|---|
| Planning | crea el set ATS → ATP → ATR, deriva TCs u outlines según la modalidad, decide las superficies UI / API / DB por triage, veto y risk score | el checkpoint de explicación de la Story: la skill explica y espera | 2 |
| Execution | corre el smoke como Go/No-Go, ejecuta los outlines, explora más allá de ellos por la trifuerza, propone bugs con la severidad ya derivada | el triage de cada bug y el alta de cada bug; cualquier recalibración de severidad en seguridad o auth | 3 |
| Reporting | llena el ATR, escribe el comentario de QA, crea y verifica los links de trazabilidad | la transición del workflow (qa_sign_off / defect_reported) | 2 |
CSA 0-5: 0 lo hace la persona · 1 aprobación por acción · 2 aprobación por plan o por lote · 3 decide dentro de límites declarados y escala fuera de ellos · 4 supervisión por monitoreo · 5 sin intervención. Ninguno de estos tres stages pasa de 3 (Regression es la excepción: puede llegar a 4 en un GO limpio), y eso es una decisión de arquitectura, no un accidente de lo que se alcanzó a construir. Ninguno de los tres lleva verificador separado: el PO/Dev y el propio checkpoint humano cumplen ese papel.
Para llevarte · handoffs y artefactos
Documentation
/test-documentation: ROI + veredictos Candidate / Manual / Deferred; crea o promueve los Tests de regresión.
Automation
/test-automation: Plan → Code → Review sobre KATA + Playwright (chequea kata-manifest.json antes de proponer ATCs).
Regression
/regression-testing: suites en CI + veredicto GO / CAUTION / NO-GO.
Artefactos que deja un run
ATS + ATP + ATR en Jira, ya cerrados · STP vivo (solo sprint-wide) · QA comment · ticket transicionado · bugs clasificados y linkeados · carpeta PBI con context.md y evidence/ · test-session-memory.md en .session/sprint-testing/<scope>/ · sesión archivada.
Tres reglas de oro
1 El orden es ley: smoke antes de trifuerza, comment antes de transición. 2 Triage de todo: el veto gana, un FAIL no es auto-Critical. 3 Trazable o no ocurrió: la cascade TC→ATS→Story (el link ATS↔Story es el coverage; ATP/ATR son administrativos).
Pruébalo: /sprint-testing single-issue UPEX-277 · ← → navegar · S presentador · O overview