AGENTIC QA · WORKFLOW SKILL

/test-documentation

El puente entre la QA manual y la automatización: analiza, prioriza con ROI y documenta test cases en el TMS con trazabilidad completa.

Documentation (históricamente Stage 4): TMS docs + ROI Analyze → Prioritize → Document US↔ATS↔ATP↔ATR↔TC Candidate · Manual · Deferred

Deck del workflow del skill /test-documentation. Regla de la casa: la mayoría de los escenarios NO se automatizan; el veredicto por defecto es Deferred. Navegación: → avanzar, S presentador, O vista general, N notas.

el mapa completo: índice mental del deck

Del comportamiento validado al repositorio de regression

ENTRADA Story QA Approved (desde /sprint-testing) Bug cerrado con fix verificado Módulo explorado end-to-end Sesión exploratoria terminada (ad-hoc)

Preflight Gate

/acli + [TMS_TOOL] operativos

RED bloqueante → STOP

→

-1

Resume check

.session/…/progress.md

resume · restart · abort

→

Modalidad TMS

gate: Xray licenciado? + {{TC_CREATION_STAGE}}

jira-xray | jira-native

→

Alcance

module · ticket · bug · discovery · ad-hoc

plan.md escrito

→

Analyze

escenarios reales + código

1 (pre+acción) = 1 TC

→

Prioritize

3 filtros + fórmula ROI

C · M · D

→

Document

crear / promover + enlazar + RTP

>10 TCs → paralelo

→

✓

Cierre

reportes, Deferred a Jira, verificador, footer

archive + mem_session_summary

Gates. Preflight con RED bloqueante → STOP; la modalidad se auto-resuelve por config y evidencia, y solo pregunta si ninguna de las dos decide.

Fallbacks. Sin work type Test Plan/Test Execution → ATP/ATR como campos de la Story; campo ausente → comment estructurado.

Loops. Bulk create interrumpido → resume despacha solo los chunks faltantes; rework de TC vía back_from_<state>.

Handoffs. Candidate → /test-automation · Manual → suite manual · Deferred → reporte + comment en Jira (terminal).

SALIDA TCs trazables US↔ATS↔ATP↔ATR↔TC Candidates en el RTP, agrupados en flujos e2e comment Deferred en Jira veredicto por TC: C / M / D

Este mapa es el índice del deck: cada nodo del camino principal es una sección que sigue. Camino principal: Gate → Resume → Modalidad → Alcance → Analyze → Prioritize → Document → Cierre. Los caminos adyacentes (gates, fallbacks, loops, handoffs) están en la franja inferior. Este es el modo document (el default); el modo repair-traceability no recorre este camino y tiene su propia slide.

mode routing: se resuelve antes del preflight

document por defecto · repair-traceability y post-promotion sellados

document (default)

Documentación normal en el TMS: Analyze → Prioritize (ROI) → Document, con veredicto Candidate / Manual / Deferred. Es el camino del mapa y del resto del deck.

workflow completo

repair-traceability

Solo con primer token repair-traceability, la frase «fix-traceability» o un pedido explícito de reparar la trazabilidad de un ticket. Carga únicamente references/repair-traceability.md. Sin ticket key, pregunta antes de tocar el TMS. No arranca Analyze → Prioritize → Document, no crea TCs ajenos ni amplía el alcance.

audit → plan → aprobación explícita → apply → verify

post-promotion

Con primer token post-promotion o con el aviso de /git-flow-master cuando una promoción llega a la rama de producción. Carga únicamente references/post-promotion-pass.md. Pasa a AUTOMATED (merged) los TCs en Pull Request cuyo ATC y cuyo spec ya están en la rama de producción, con CI en verde, y relee cada estado. No analiza, no puntúa ROI ni crea TCs.

ATC + spec por path + CI → merged → releer

Host	Cómo se invoca
Claude Code	/test-documentation UPEX-101 · /test-documentation repair-traceability UPEX-101 · /test-documentation post-promotion
OpenCode · Codex	en prosa: «cargá la skill test-documentation, modo repair-traceability, ticket UPEX-101» · «modo post-promotion»
Regla	el primer token que coincide con un modo ES el modo y el resto se reenvía; sin modo → document para trabajo de documentación; si el pedido podría ser más de uno, pregunta

Un ticket solo no ve la falla que más importa

Un link de coverage invertido es invisible en su Story: el link existe y el panel queda vacío. Por eso, al auditar un ticket, el modo ofrece también el barrido project-wide de dirección mixta (varias keys o una JQL → una sola worklist). Corregir dirección es borrar antes de recrear: Jira deduplica par + tipo, así que agregar el link corregido sin borrar es un no-op silencioso. El plan que aprobás dice qué links se borran, por id, y repara hacia el camino del ATS, nunca con links directos TC→Story en masa.

Mode routing de SKILL.md. repair-traceability recorre la cascade en orden: ① TC en ATS y ATS→Story (llena el panel) ② TC solo vía ATP (ubicado, sin coverage) ③ TC→Story directo (last resort válido) ④ sin camino (huérfano). Canon de dirección, borrar-antes-de-recrear y barrido: agentic-qa-core/references/traceability-linking.md §4 y §10. Credenciales faltantes siguen siendo un STOP duro (Critical Rule #10).

antes de la fase 1: tres candados

Nada se documenta sin pasar los gates

Prerrequisito duro

Solo comportamiento ya validado: Story QA Approved, bug cerrado, o sesión exploratoria terminada. El TMS documenta y protege regression, no es una herramienta de exploración (explorar es de /sprint-testing).

Preflight Gate

REQUIRED: issue-tracker operativo (/acli, valida con bun run jira:check) + modalidad TMS resoluble (jira-xray → /xray-cli + creds XRAY_*). OPTIONAL: repos fuente legibles. No toca entorno vivo → sin probes de DB/API/browser. Gaps → UNA checklist; RED bloqueante → STOP.

Fase -1 · Resume check

Lee .session/test-documentation/<scope>/progress.md. Si existe: muestra scope, modalidad, última fase completada y chunks pendientes → ofrece resume / restart / abort (restart archiva primero).

El caso de resume que más importa

Bulk create de la Fase 3 interrumpido a mitad de lote: progress.md registra cada chunk completado (uno por subagente), así que resume salta los TCs ya creados y despacha solo los chunks faltantes.

Los tres candados corren en orden: prerequisito de comportamiento validado (conceptual), preflight de capacidades (mecánico: acli + TMS), y resume de sesión. El skill no ejecuta contra un sistema vivo; su gate se centra en poder ESCRIBIR en el TMS.

fase 0: gate obligatorio, se resuelve UNA vez

Xray licenciado? Mismos conceptos, distintos contenedores

Config

{{TMS_CLI}} = bun xray → candidato jira-xray, se confirma en el paso 2; acli-solo o sin definir → jira-native.

Evidencia

La API de Xray responde vía /xray-cli (auth status y una lectura del proyecto) → jira-xray. Los work types solos nunca deciden: también existen nativos en jira-native. Sin respuesta nunca es jira-xray: si la config nombró Xray, STOP por la Regla #10 y nombrar las XRAY_*.

Preguntar

Solo si ni la config ni la evidencia deciden. Persistir en plan.md; sticky; drift a mitad de sesión → STOP y pregunta.

Artefacto	jira-xray	jira-native (sin Xray)
ATP	Issue Test Plan «ATP: {STORY}: {título}»	Mismo issue Test Plan por excelencia; fallback: campo de la Story → comment
ATR	Issue Test Execution con Test Runs por TC	Mismo issue Test Execution; fallback: campo de la Story → comment
TC	Xray Test (Manual / Cucumber / Generic)	Issue type Test nativo; la Description lleva el template completo
ATS (Test Set) / Pre-Condition	First-class; membership = link TC→ATS + la membership Xray-internal (GraphQL), nunca en lugar del link	Work type presente → mismo item, membership = los mismos links TC→ATS; ausente → sin ATS, links directos TC→Story
Result sync (CI)	Import Results JUnit/Cucumber → runs auto	Script actualiza Test Status + comment por build

Items-first en AMBAS modalidades: Test Plan y Test Execution son work types nativos de Jira, independientes de Xray; el campo de la Story es un fallback degradado solo cuando el work type no existe en la instancia. Nunca mezclar modalidades dentro de una misma Story (anti-patrón D5). TC en ATS es siempre un link TC→ATS en ambas modalidades (canon: traceability-linking.md §9).

fase 0: el mismo gate resuelve un segundo valor

{{TC_CREATION_STAGE}} elige el verbo de la Fase 3

La modalidad dice qué herramienta TMS está viva. testing.tc_creation_stage en .agents/project.yaml dice si este skill crea los Tests Candidate / Manual o refina y promueve los que /sprint-testing ya hizo. Sin definir o no reconocido → auto.

Valor resuelto	Verbo de la Fase 3 para un escenario Candidate / Manual
auto (default)	jira-xray → promover + enriquecer un Test de sprint existente · jira-native → crear el Test acá
sprint-testing	promover + enriquecer en AMBAS modalidades: los items ya existen y crear otro duplica el repositorio
test-documentation	crear en AMBAS modalidades: no hay items de sprint para promover

Promover sin Test de sprint → crear

Si el verbo dice promover pero el escenario no tiene Test de sprint (Story testeada antes de fijar el valor, o escenario derivado recién ahora), se crea para ese escenario y se anota en progress.md. Nunca se salta el TC.

Los TCs de sprint son borradores

Se escribieron para correr una vez. Antes de entrar a regression se refinan: título canónico, pasos repetibles, precondiciones construibles desde un entorno frío, variables en lugar de ids, split o merge por identidad. Cada TC refinado lleva una línea Refinement Notes.

Modalidad y {{TC_CREATION_STAGE}} se persisten juntos en plan.md §Inputs y son sticky. La tabla completa del knob vive en sprint-testing/SKILL.md §"Which stage creates the TCs"; test-documentation solo la consume. Cualquiera sea el verbo, la regla del título canónico es la misma (ver la slide de promoción al RTP).

elige el alcance por la ENTRADA, no por la salida

Los alcances, un solo pipeline

Alcance	Entrada	Volumen típico	Sesgo por defecto
Module-driven	un módulo explorado de punta a punta	20-100+ escenarios	la mayoría terminará Deferred
Ticket-driven	una Story QA Approved del sprint	3-8 escenarios	ATP/ATR por Story
Bug-driven	un bug cerrado con fix verificado	0-2 escenarios	ROI sesgado ARRIBA, «falló una vez, puede fallar de nuevo»
Ad-hoc / Exploratory	escenarios nuevos de exploración	1-10 escenarios	aplica los 3 filtros con dureza
Discovery-driven	una brecha sin Story, anclada a una Tech Story de cobertura	1-10 por brecha, 20-100+ por módulo	nada marcado «observed» llega a Candidate sin que una persona confirme que es intencional; entra desde la gap list o desde una ronda exploratoria: COVERED se descarta con una línea, WEAK es una propuesta de reforzar el test existente, y la alarma del 50% corre por chunk de una Tech Story

Al confirmar el alcance, la IA escribe el plan

<scope> = <JIRA-KEY> (ticket/bug) · <module-slug> · <YYYY-MM-DD>-adhoc. Escribe .session/test-documentation/<scope>/plan.md: goal (scope + modalidad + nº de TCs esperados), inputs (PBI, ATP, bugs previos), fases, riesgos y checklist de verificación, y registra el checkpoint en progress.md.

Un ID de Story → ticket-driven · un ID de bug → bug-driven · una Tech Story de cobertura → discovery-driven · un nombre de módulo → module-driven · notas de sesión → ad-hoc.

Los alcances comparten el pipeline Analyze → Prioritize → Document; solo cambian la fuente de entrada y los defaults. El plan-first es obligatorio (contrato de sesión): nada se crea en el TMS sin plan.md escrito.

alcance bug-driven: la regla que vale oro

Un bug importante DEBE terminar con un Test

Es candidato de regression?

Aplica los filtros de la Fase 0 + ROI (el bug previo sesga hacia arriba). NO → trátalo como un test fallido: el fix ya se verificó en sprint-testing → Deferred, sin Test nuevo. SÍ → paso 2.

Vino de un Test ya ejecutado que falló?

SÍ → REUTILIZA ese Test: enlázalo al bug (tests / is tested by) y promuévelo a regression, nunca dupliques. NO → CREA + diseña el Test (native: issue Test; xray: Xray Test + Test Plan / Test Set).

Anula «el bug es el test case»

Esa frase de /sprint-testing cubre solo el retest inmediato del sprint, NO la regression futura. Esta regla decide si debe existir un Test persistente para que el bug nunca regrese en silencio.

Nunca reabras un bug cerrado (D8)

La historia del bug es inmutable. Crea el TC nuevo y enlázalo vía tests / is tested by, no adjuntes regression reabriendo el issue.

Un bug cerrado es evidencia empírica fuerte de que el área regresa: la mayoría califica y se inclina a Candidate, aunque no todos (un typo puntual en un área estable se difiere). La decisión reuse-or-create evita duplicar Tests que ya existen en el set.

fase 1: analyze · qué entra

Reúne las fuentes, y luego lee el código

Fuente	Qué se lee	Por qué
Story / Epic	carpeta sincronizada completa: story.md, acceptance-criteria.md, scope, business rules, comments.md	identificar escenarios + señales de riesgo
Bugs cerrados enlazados	summary, causa raíz, área del fix	regla de priorización por bug previo
ATP / ATR existentes	lectura modality-aware vía bun run jira:sync-issues get <KEY> --include-comments → leer el .md sincronizado	escenarios y resultados que ya existen, no reinventar ni re-ejecutar
Implementation plan + código	archivos reales, APIs, test IDs	validar diseño vs implementación
business-domain-context	nombres canónicos de entidades y procesos (bun run context:map business-domain-context)	vocabulario de títulos, pasos y precondiciones

Validación contra código fuente: obligatoria antes de documentar

El ATP se escribió ANTES de que el código existiera. Grep a data-testid=, route handlers, rutas de API y formatos de texto; toda divergencia va a una sección Refinement Notes del TC. Saltarse este paso es la causa nº1 de tests automatizados inválidos después.

Lecturas detalladas SIEMPRE por el script de sync (acli view devuelve null en custom fields). Discrepancias típicas: una API asumida que en realidad es SSR/DB directa; "based on N reviews" vs el real "(N reviews)"; IDs hardcodeados vs patrón de variable.

fase 1: analyze · las dos reglas portantes

Una (Precondición + Acción) = un TC

✓ MISMO TC: 5 aserciones

pre credenciales válidas, acción enviar login
redirección + token + perfil vía /auth/me + cookie + bienvenida
todas las validaciones viven en UN TC, dividir «panel A / B / C» es el antipatrón más diagnosticado

≠

✓ TC DISTINTOS: la precondición difiere

credenciales válidas → éxito (TC-A)
cuenta bloqueada → 423 (TC-B)
credenciales inválidas → 401 (TC-C)

Cross-cutting (NO es un TC)	Se valida…
Responsive · XSS · performance · a11y · contrato de API · «manejo de errores» genérico	dentro de cada test (viewport móvil, datos con caracteres especiales, aserciones de tiempo/a11y/schema) o en una suite a nivel de app
Deferral ≠ omission	mover un rasgo transversal fuera del alcance es un handoff explícito: nombra la suite receptora o registra el gap (TC Deferred o nota en el ATR), nunca se evapora

Un escenario real es un flujo de usuario: objetivo de negocio claro, precondición + acción concretas, resultado verificable. Los rasgos transversales se prueban DENTRO de otros tests o en suites app-level; promover "prevención XSS" a TC propio es error clásico.

fase 1: analyze · doctrina de diseño (test-design-doctrine.md)

Un AC → N candidatos, elegidos por la forma del AC

Disparador en el AC	Técnica (obligatoria)	Qué produce
Cualquier input (siempre)	Equivalence Partitioning	mismo output → UN TC parametrizado (Scenario Outline + Examples); output distinto → TCs separados
Rango / límite / longitud / ventana de fecha	Boundary Value Analysis	min-1 · min · min+1 … max-1 · max · max+1 + cero / vacío / null / overflow
Campo de estado / ciclo de vida	State-Transition	un TC por transición válida + por transición inválida
2+ condiciones que interactúan	Decision Table	enumera combos, colapsa equivalentes, un TC por regla sobreviviente
3+ factores combinables	Pairwise	conjunto all-pairs (registra la reducción)

Candidatos ≠ items del TMS

Derivar amplio es gratis; persistir está gateado por ROI (Fase 2). Colapsar un AC a un solo TC exige justificación escrita «trivially atomic». El mapa AC→TC es el piso, no la cobertura.

Improvement bridge

Un test-beyond-AC expone un gap porque el AC estaba infra-especificado → el artefacto correcto es un issue Improvement (doctrina de defect-management), NO un TC de regression ni ensanchar los ACs de la Story después del hecho.

EP sin BVA pierde el off-by-one. La regla de identidad (pre+acción) solo fusiona DENTRO de una partición, nunca a través de particiones, límites o estados. Canon: agentic-qa-core/references/test-design-doctrine.md.

fase 2: prioritize · el gate que nunca se salta

Tres filtros, luego la fórmula

Protege contra regressions futuras?

Typo puntual en un área estable → No → Deferred.

Bugs previos en esta área?

Sí → prioriza aun con ROI moderado: «falló una vez, puede fallar de nuevo».

Nivel de app o de feature?

XSS / a11y / perf / responsive → suites APP-level → Deferred desde este alcance.

Falla cualquier filtro → Deferred

Los tres filtros matan a la mayoría antes de hacer aritmética.

ROI = (Frequency × Impact × Stability) ───────────────────────────────── / 10 (Effort × Dependencies) / 10 = constante de normalización todo en 3 → 0.3 → Deferred (el default) Component Value = ROI × (1 + 0.2 × N) N = flujos E2E que reutilizan el TC estimado, tope N = 3 (máx. ×1.6)

Factor (1-5)	1	5
Frequency	anual	cada PR / commit
Impact	cosmético	ingresos / core
Stability	muy volátil	meses sin cambios
Effort (÷)	trivial	semana+
Dependencies (÷)	ninguna	externos complejos

Effort y Dependencies son DIVISORES: un "flujo crítico" caro y acoplado DEBE puntuar bajo, y eso es la fórmula funcionando. El "/ 10" no es un sexto factor: lleva el cociente crudo (0.04 a 125) a la escala de los umbrales (0.004 a 12.5). Component Value rescata átomos reutilizables: authenticateSuccessfully con ROI 2.0 reutilizado en 3 flujos → 2.0 × 1.6 = 3.2 → Candidate. N es una estimación cualitativa (nadie cuenta call-sites), con tope 3; se anota en el comment de ROI. Bandas autoritativas: references/tms-conventions.md §9.

fase 2: prioritize · exactamente uno de tres, no hay cuarto

Candidate · Manual · Deferred: la modalidad cambia el verbo

Veredicto	Lo dispara	A dónde va	Fase 3 (auto): jira-native	Fase 3 (auto): jira-xray
Candidate	ROI > 3.0 · O 1.5-3.0 + bug previo · O happy path crítico	alimenta /test-automation	se CREA el work item Test (solo C + M)	el Test ya existe (Planning de sprint-testing) → se PROMUEVE al Regression Test Plan (RTP) (+ TS: de feature opcional), label regression-candidate, y se ENRIQUECE (Gherkin rico, parametrización, edge cases)
Manual	ROI 0.5-1.5 y no automatizable, o solo-manual explícito	suite de regression manual (terminal)	se CREA el work item Test (solo C + M)
Deferred	ROI < 0.5 · O falló un filtro · O validación one-time · O no encaja en ninguna fila de arriba (es el bucket por defecto)	fuera de regression (terminal, revisitable)	NO se crea: queda en el reporte y en el comment de Jira	el Test de sprint queda sin promover; no se borra

Tres capas, tres conteos: la forma saludable

analizados 80 → documentados 12 → automatizados 8. Un test entra al repositorio porque será re-ejecutado, nunca para alcanzar un conteo. Si >50% termina Candidate/Manual → reaplica los filtros con más rigor: la mayoría debe ser Deferred.

El agente puntúa. La persona firma.

El agente deriva escenarios por técnica, calcula el ROI y propone el veredicto. Cada veredicto lo firma la persona, igual que la épica de regresión y el Test Set. Autonomía CSA 2, verificador separado recomendado: un segundo agente re-lee los veredictos contra el ATR. La alarma del >50% Candidate/Manual se responde, no se ignora.

El veredicto (aritmética) es idéntico en ambas modalidades; lo que cambia es el verbo de la Fase 3: con {{TC_CREATION_STAGE}} = auto, CREAR (native) vs PROMOVER + ENRIQUECER (xray); los otros dos valores fijan el verbo en ambas. Deferred nunca es un borrado. Anti-patrón D4: nunca saltarse el scoring de ROI. Contrato agéntico del stage: agentic-qa-core/references/stage-gates.md.

fase 3: document · preflight de contenedores

Epic · Test Set · Test Plan: tres cosas distintas

Regression Epic

= el epic de proceso «QA Test Repository». Resolver found-or-created por JQL (type = Epic AND summary ~ "QA Test Repository"); si falta, pregunta antes de crear y cachea la key en .agents/project.yaml. Todo TC documentado se parenta aquí, nunca a un epic de producto.

paraguas del repositorio

Test Set, dos altitudes

ATS per-Story (obligatorio): ATS: {US_ID}: {story title}, tercer artefacto de la familia ATP/ATR/ATS, parent «QA Test Artifacts», components heredados de la Story. Su link is tested by a la Story es lo que llena el panel de coverage. TS: feature-level (opcional): TS: {EPIC|module}: Validate {feature}, agrupa smoke/regression, components opcional. Native sin work type Test Set → links directos TC↔Story.

coverage

Test Plan

Alcance de ejecución / regression, el conjunto de Tests que corre para un release o ciclo. El ATP en jira-xray ES un issue Test Plan (parent: epic «QA Master Test Plan»). El RTP (RTP: {PROJECT_KEY|module}: Regression Test Plan) es el Test Plan long-lived de regression bajo ese mismo epic: destino de cada TC promovido con label regression-candidate, y nunca se completa: cada corrida regular de /regression-testing escribe su RTR (Test Execution RTR: {scope-id}: Regression Testing) contra él; el STR queda para el cierre del sprint.

ejecución

Modelo de tres ejes (defect-management-doctrine.md)

Parent = bucket de proceso QA (Test → «QA Test Repository» · ATP → «QA Master Test Plan» · ATR y ATS → «QA Test Artifacts») · issue-link = la Story origen · components = el módulo de producto afectado. Tres ejes separados; el parent nunca lleva la traza de producto.

La gente fusiona estos contenedores rutinariamente. Epic = repositorio completo; ATS = el Set per-Story que da coverage (TS: opcional agrupa por feature); Test Plan = alcance de ejecución. En jira-native con work type Test Set el ATS existe igual (membership = links TC→ATS); sin work type, links directos TC↔Story + Regression Epic + label.

fase 3: document · el orden no es opcional

Set-first: ATS → ATP → ATR → recién entonces cada TC

1 Find-or-create ATS → link a la US («is tested by») ← ESTE link llena el panel de coverage 2 ATP (item nacido en sprint-testing Planning; find-or-create aquí SOLO en module-driven) → link a la US (administrativo, sin coverage) 3 ATR → link a la US (administrativo) + link ATP↔ATR (plan/results, 1:1) 4 por cada TC: link TC→ATS (ambas modalidades) + xray: membership Xray-internal listas de ATP/ATR derivadas del ATS TC→Story directo = last resort válido 5 por cada TC PROMOVIDO: PRIMERO título re-derivado y verificado xray → TS: feature (opcional) + RTP + label regression-candidate native→ label de feature/Epic

Entidad	Naming
ATP	ATP: {STORY-KEY}: {story title}
ATR	ATR: {STORY-KEY}: Story Testing
ATS	ATS: {US_ID}: {story title}, obligatorio per-Story, aunque tenga 1 TC
RTP	RTP: {PROJECT_KEY\|module}: Regression Test Plan, plan long-lived de regression, uno por proyecto: destino de cada TC promovido
TC	{US_ID}: TC#: should <outcome> [when <condition>] [given <pre>], prefijo SIEMPRE el US key, en toda modalidad
Agrupación	TS: {EPIC\|module}: Validate {feature}, agrupador feature-level opcional (Test Set / describe())

Huérfano = TC sin NINGÚN camino a la Story

Ni ATS, ni ATP, ni link directo → test-documentation modo repair-traceability verifica la cascade TC→ATS→Story → TC→ATP→Story → TC→Story. D7: un ATR nunca se enlaza a dos ATPs (1:1). Rechaza títulos «Login test», «Login - error», «TC1: Test form».

Coverage verificado live: SOLO el link ATS→Story (o los links directos Test↔Story) llenan el panel; los links ATP→Story y ATR→Story son trazabilidad administrativa. Cascade de resolución: TC→ATS→Story (primaria) → TC→ATP→Story (placement, no cubre panel) → TC→Story directo (last resort válido; el defecto es no tener ningún camino). La membership TC en ATS es siempre un link TC→ATS en ambas modalidades; jira-xray además escribe la membership Xray-internal (GraphQL vía /xray-cli), nunca en lugar del link. TC en ATP / ATR sigue siendo Xray-internal. Canon: traceability-linking.md §9.

fase 3: document · el verbo por modalidad, TC por TC

Crear los TCs: matriz por modalidad

Stack	Test manual	Candidate (automatizable)
Xray on Jira	Dos pasos: (1) Create Test type=Manual SIN steps inline (Xray Cloud los descarta en silencio), (2) Add Test Step uno a uno (verifica con Get Test), luego Update Issue con la Description completa	Create Test type=Cucumber gherkin=… + Update Issue con el template de Description
Jira native	Create Issue issueType=Test, Description = tabla de pasos	Create Issue issueType=Test, Description = Gherkin + template completo

La regla de las dos llamadas de Xray

Una Create Test (registra en Xray) + una Update Issue (pega la Description). Saltarse la segunda deja un TC sin documentación legible en Jira: el fallo silencioso más común.

Anti-patrones D1 · D6

Nunca escribas ADF JSON a mano: 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. Nunca fabriques customfield_NNNNN: corre bun run jira:sync-fields --force y resuelve por {{jira.<slug>}}.

Description siempre con el template completo: Related Story · Priority · ROI · Prior bugs · Test Design (gherkin/steps) · Variables · Implementation Code · Architecture · Test IDs · Preconditions · Expected Results. Cada TC creado: parent «QA Test Repository», components = módulo de producto afectado, assignee = el usuario de la sesión, puesto al crear.

La dispatch de esta fase es la única paralela: N > 10 TCs → subagentes en chunks de 5-10 (ver slide de orquestación). Cada subagente carga /xray-cli o /acli según modalidad y corre este flujo serial para su chunk.

fase 3: document · el artefacto que viaja a automatización

Gherkin de alta calidad: variables, nunca datos duros

TC · UPEX-101.feature

@critical @regression @automation-candidate @UPEX-101
Scenario Outline: should show auth error when password is incorrect
  """  Bugs covered: UPEX-202 · Related Story: UPEX-101 · ROI: 4.0  """
  # === PRECONDITIONS ===
  Given a verified user exists with {email}
  # === ACTION ===
  When the user submits login with {email} and {wrong_password}
  # === VALIDATIONS ===
  Then a 401 error is returned with "<message>"
  # === EQUIVALENT PARTITIONS ===
  Examples: Wrong password | Empty password | Unknown email

Variables, nunca hardcode. {mentor_id}, no 550e8400-…. Tabla de Variables con cómo obtener cada valor en runtime.
Tags siempre: prioridad (@critical…@low) + suite (@regression, @smoke si ruta crítica) + @automation-candidate + @{US_ID}.
Comentarios estructurados: PRECONDITIONS / ACTION / VALIDATIONS / EQUIVALENT PARTITIONS.
Docstring con metadata: story, bugs cubiertos, ROI.
Parametriza por partición: variantes de mismo comportamiento → UN Test con Examples, no N Tests.

Los datos de staging cambian con los años: un UUID o email literal pudre el test. Cada variable lleva su query de obtención ({email} → SELECT email FROM users WHERE active=true LIMIT 1). Este Gherkin es exactamente lo que /test-automation consumirá.

fase 3: el veredicto decide la rama del workflow

Cada veredicto es un estado, ninguno es «dejarlo donde esté»

Draft ──start_design──▶ In Design ──ready_to_run──▶ Ready ──┬── for_manual ─────────────────▶ Manual (terminal) └── automation_review_from_ready ▶ In Review ──approve_to_automate──▶ Candidate → /test-automation

Veredicto	Transiciones a disparar	El TC termina en
Candidate	automation_review_from_ready y luego approve_to_automate	candidate: lo que toma /test-automation
Manual	for_manual, desde ready, nunca vía in_review: esa arista no existe en el catálogo. Un TC ya en candidate baja con manual_execution_from_candidate	manual
Deferred	ninguna	ready (jira-xray: el Test de sprint sin promover · jira-native: no se creó TC)

Nunca saltes estados. Rework solo vía back_from_<state>. Slugs desde .agents/jira-workflows.json ({{jira.transition.test_case.<slug>}}), nunca nombres literales hardcodeados.
Slug sin mapear (estados renombrados o catálogo viejo): fallback de artifact-lifecycle.md §4. Lista las transiciones vivas, propone el sinónimo más cercano en UNA pregunta, dispara el id vivo si decís que sí y recomienda bun run jira:sync-workflows. Nunca queda un TC en draft por un slug que no resolvió.
Labels base por TC. alcance: regression casi siempre, smoke solo ruta crítica (10-20% de la suite), + e2e/integration/functional · estado: automation-candidate ↔ manual-only excluyentes; al mergear → automated.

Dos campos independientes: Test Status (workflow: dónde está en su vida) vs Execution Status (la última run). "Candidate" con última run FAIL es una combinación válida. Canon del mapa veredicto → estado: agentic-qa-core/references/artifact-lifecycle.md §1 y §1.1.

fase 3: el último paso, a dónde van los Candidates

Promover: título primero, label y membership al final

Re-derivar

El título sale de Precondición + Acción + resultado verificable del TC, nunca de la redacción del outline de sprint.

Conservar el prefijo

{US_ID}: TC#: no cambia. # es un índice estable dentro de la Story: si un hermano quedó Deferred, el hueco queda.

Reescribir

Si el summary vivo difiere, [ISSUE_TRACKER_TOOL] Update Issue: el summary es un campo de Jira, nunca pasa por [TMS_TOOL].

Verificar, recién ahí promover

Título válido → label regression-candidate + RTP. El cambio viejo → nuevo queda en progress.md.

El RTP, uno por proyecto

RTP: {PROJECT_KEY|module}: Regression Test Plan, parent «QA Master Test Plan», find-or-create (pregunta antes de crear). Assignee = vos al crear: Xray rechaza ediciones de membership en un Test Plan que no es tuyo; si aparece uno ajeno, pregunta antes de reasignar. Pasa a ready con la primera promoción y ahí se queda, nunca complete. Manual entra al mismo RTP con manual-only; Deferred nunca. /test-automation y /regression-testing leen de ahí: un Candidate fuera del RTP no existe downstream.

Agrupar en flujos e2e

Un grupo = un journey que un spec corre de punta a punta, con nombre de journey («Checkout, compra de invitado», no «Checkout tests»). Un TC que usan 2+ flujos es un componente atómico (un Steps module en KATA): se lista bajo cada flujo y su cuenta es la N del Component value. Se escribe en la descripción del RTP, sección ## Regression flows (la copia durable) y como columna en COVERAGE-MATRIX. Un Candidate sin flujo es una alarma, no una categoría.

Secciones "Title on promotion" y del RTP handoff en SKILL.md. La regla del título vale para todo camino de escritura: jira-xray (un Test de sprint seleccionado al RTP) y jira-native (un Test de Stage 4 creado desde un outline de sprint). En jira-native la promoción también viaja en labels del Test; /regression-testing describe cómo lo lee. Ciclo de vida: RTP nace en planning, designed → ready, nunca complete; feature TS queda en designing hasta que cierra su Epic; Preconditions quedan en active.

fase 3: dos archivos locales y un registro que sobrevive

Los reportes son [LOCAL]; lo que queda es el TMS

Archivo (.context/reports/, gitignored)	Contiene
COVERAGE-MATRIX-<scope>.md	AC → escenario → TC key → veredicto, más el flujo e2e de cada Candidate; los ACs sin cubrir
PRIORITIZATION-<scope>.md	cada escenario con sus cinco factores, el score y el veredicto

[ISSUE_TRACKER_TOOL] Add comment: issue: {SCOPE_KEY} body: | ## Prioritization — Deferred scenarios | Scenario | ROI | Why deferred | |---|---|---| | <scenario> | <score> | <gate / band / one-time> |

Read-before-write: si el comment ya existe de una corrida anterior sobre el mismo scope, se reemplaza, no se apila otro. Scope de módulo sin issue dueño → va al Regression Epic.

Ningún reporte es entregable. Existen solo en la máquina que corrió la sesión; nada downstream depende de ellos. Un re-run sobre el mismo <scope> sobrescribe su propio par.
Registro durable. Candidate y Manual: los Tests con su comment de ROI. Deferred no crea item, así que su lista se espeja en el comment de la izquierda.
test-cases/ es caché [SYNC]. El skill corre bun run jira:sync-issues get <STORY_KEY> y LEE test-cases/TEST-<KEY>-<slug>.md; nunca escribe ahí. Se recupera con bun run context:hydrate. Lo Xray-internal (Preconditions, membership de Test Set) lo completa bun xray test enrich.
Checkpoint + Archive. Cada fase y cada chunk paralelo se apendan a progress.md; con los dos reportes y el comment Deferred listos, la sesión se archiva en .session/.archive/… + mem_session_summary. Falla parcial (429s) → no se archiva: resume retoma los chunks.

<scope> es el mismo valor que la carpeta de sesión: <JIRA-KEY>, <module-slug> o <YYYY-MM-DD>-adhoc. .context/reports/README.md explica por qué la carpeta está ignorada. bun xray test enrich es un comando de /xray-cli: cargá ese skill antes de invocarlo.

cierre del stage Documentation: dos cosas antes de decir «listo»

Verificador liviano + footer de sesión

Light stage verifier: Documentation (líneas propias) [ ] cada TC existe por KEY · parent QA Test Repository · components · assignee = self [ ] cada TC salió de draft: Candidate en candidate, Manual en manual, Deferred dejado en ready a propósito [ ] título canónico verificado ANTES de label y RTP [ ] RTP en ready · assignee = self · NO completado [ ] promovidos en el RTP (y TS: opcional), membership ok [ ] cada Candidate en un flujo e2e con nombre, escrito en ## Regression flows del RTP [ ] Preconditions en active (sin transición: N/A) [ ] slug sin mapear → fallback §4 preguntado

Más las ocho líneas comunes de artifact-lifecycle.md §5. Cada línea es YES o un N/A con motivo; un solo NO deja el stage en NEEDS REVISION.

footer, solo en el chat

Skills loaded: test-documentation, acli, xray-cli
MCPs used: none
CLIs used: acli, bun (xray, jira:sync-issues)
Testing levels touched:
- API: 6 Candidates
- UI/E2E: 2 Candidates, 1 Manual
- Unit: none
Refinements proposed: 0

Framing: curación. «Testing levels» dice cómo se reparten por nivel los TCs procesados en la sesión; un nivel esperado y no tocado dice none.
Capturas, si las hay: ruta relativa al instante y consolidada al cierre. Footer y capturas van solo al chat, nunca a un comment de Jira ni al ATR.
Lecciones se proponen en .session/test-documentation/<scope>/refinements.md; nunca se aplican a la skill viva.

Canon: agentic-qa-core/references/artifact-lifecycle.md §5 (verificador) y session-footer-contract.md (footer). En sesiones con subagentes, cada reporte de stage trae los cinco campos del footer y el orquestador lo compila una sola vez al cierre.

quién hace qué: centro de comando + subagentes

El hilo principal decide; los subagentes escriben

Inline (orquestador)

Fases -1, 0, 1 y 2: resume, modalidad, análisis y veredictos viven en el hilo principal; planificar y decidir no se delega.

criterio

Paralelo (Fase 3, N > 10)

Chunks de ~5-10 TCs por subagente, cap = 10 subagentes (Jira/Xray throttlean y devuelven 429; el cap está en SKILL.md §Subagent Dispatch). Cada subagente carga /xray-cli o /acli. N ≤ 10 → inline.

fan-out

Error protocol

Fallo de subagente → STOP, reporta el estado parcial (qué TCs aterrizaron, cuáles no, con keys/errores) y ofrece retry / skip / abort. Sin auto-fix, sin rollback.

seguridad

Necesidad	Herramienta	Nota
Lecturas detalladas (custom fields, ACs, ATP/ATR, comments)	bun run jira:sync-issues get <KEY> --include-comments	leer el .md sincronizado, acli view devuelve null en custom fields
Escrituras TMS (Test / Plan / Execution / link / transición)	/xray-cli (jira-xray) · /acli (jira-native + Jira genérico)	cargar el skill ANTES de invocar el binario
IDs de campos / workflows	bun run jira:sync-fields + {{jira.<slug>}}	anti-patrón D6
Validación de código fuente	Grep / Read sobre el repo	sin entorno vivo, solo lectura de código

La división es deliberada: el criterio queda en el centro de comando; las escrituras crudas de API se reparten con tope de concurrencia. El enlazado de trazabilidad y la matriz de cobertura corren inline al final porque necesitan el estado agregado de todo lo creado.

todo el mapa, en una invocación bug-driven

Una corrida de documentación, de punta a punta

claude-code

> /test-documentation UPEX-202 (turn this closed bug into a regression test)

[Modo]      document (default). [Preflight] acli + xray-cli OK → GREEN.
[Fase -1]   Sin sesión previa para UPEX-202. [Fase 0] jira-xray ({{TMS_CLI}} = bun xray, la API de Xray responde)
            · TC_CREATION_STAGE auto → verbo: promover. Ambos sticky en plan.md.
[Fase 1]    jira:sync-issues get UPEX-202 + Story UPEX-101 (--include-comments).
            Grep: data-testid="login-error" confirmado · ruta /api/auth/login.
[Fase 2]    F2 bug previo = SÍ. ROI = (4×5×4)/(2×1)/10 = 4.0 → CANDIDATE.
            Regla de oro: no vino de un Test fallido → CREAR (anotado en progress.md).
[Fase 3]    Plan: Test Cucumber «UPEX-101: TC2: should show auth error when password
            is incorrect» · parent QA Test Repository · components Auth · assignee yo
            · link TC→ATS UPEX-410 + membership Xray · tests → UPEX-202
            · RTP UPEX-12 + regression-candidate · flujo «Login, usuario registrado». Procedo?
> y
  UPEX-540 creado (Create Test + Update Issue) · draft → … → candidate · RTP en ready.
  sync get UPEX-101 → test-cases/TEST-UPEX-540-….md leído. Reportes [LOCAL] escritos;
  Deferred: ninguno. Verificador: todo YES o N/A · footer impreso en el chat.

Cada regla del deck es visible aquí: modo, preflight, resume, gate de modalidad + {{TC_CREATION_STAGE}}, plan-first, lectura por sync script, grep de código, regla del bug previo, ROI con su /10, regla de oro reuse-or-create (y el fallback de promover a crear cuando no hay Test de sprint), naming, parent + components + assignee, link TC→ATS más la membership Xray, promoción al RTP con flujo e2e, lectura del caché sincronizado, reportes locales, verificador y footer. Todo detrás de una confirmación antes de escribir. El ATS UPEX-410 ya existía desde la Planning de /sprint-testing.

cierre: dónde encaja y cómo se invoca

Deriva amplio · documenta lo repetible · automatiza los pocos

Cómo invocarlo

Claude Code: /test-documentation <KEY>, /test-documentation repair-traceability <KEY> o /test-documentation post-promotion. OpenCode y Codex: «cargá la skill test-documentation, modo <modo>». También por frases: «document tests», «ROI analysis», «which tests to automate», «fix-traceability».

Handoffs en el pipeline

Entra desde /sprint-testing (Story QA Approved, bug cerrado). Sale hacia /test-automation, que re-alcanza los Candidates: module → Macro · ticket → Medium · bug → Micro (ad-hoc entra donde encaje). Manual y Deferred son terminales.

Artefactos que deja

Durable, en el TMS: TCs enlazados US↔ATS↔ATP↔ATR↔TC con su comment de ROI · Candidates en el RTP con ## Regression flows · comment Prioritization con los Deferred. Local: los dos reportes [LOCAL] de .context/reports/, el caché [SYNC] de test-cases/ (se lee, no se escribe) y la sesión archivada en .session/.archive/.

Las tres reglas para llevar

1. Por defecto, Deferred: 3 filtros + ROI = (F×I×S)/(E×D)/10. 2. Una (precondición + acción) = un TC; los rasgos transversales viven dentro de los tests. 3. Set-first: ATS → ATP → ATR → TC, y un bug importante siempre termina con un Test.

Cierre: Documentation es el puente entre la QA manual (Planning · Execution · Reporting) y la automatización (Automation). La IA acelera el oficio; el criterio y las confirmaciones siguen siendo del humano.