Agentic QA · Skill de contexto del proyecto

/project-context

Le da a la IA el mapa del sistema bajo prueba: genera y actualiza los mapas de negocio (datos, API, E2E) y el Master Test Plan, sección por sección y siempre con tu aprobación antes de pisar algo que ya existe.

Un modo por corrida UPDATE: solo lo viejo, diff y OK El MTP vive en Jira

Deck de la skill project-context, de tipo workflow. Es dueña de los artefactos de contexto que se regeneran: los tres mapas de negocio que viven dentro de sus skills de contexto y el Master Test Plan. Además crea skills de contexto propias del proyecto para otros aspectos. Pulsá → para avanzar, S para modo presentador, O para overview, F para pantalla completa.

Alcance · 2 de 16

Cuándo usarla y cuándo pasarle la posta a otra

Usala para

Generar o refrescar el mapa de datos, de API o de E2E del sistema bajo prueba.
Escribir o actualizar el Master Test Plan: qué testear y por qué, rankeado por riesgo.
Refrescar todo en orden, cuando lo pedís explícitamente (refresh-all).
Crear una skill <aspect>-context propia del proyecto para un aspecto que las skills que vienen con el boilerplate no cubren.
Ver qué hace el producto que ningún test ejercita, ordenado por riesgo (coverage).

No es su trabajo

Pedido	Va a
Mapa de dominio o de infraestructura	/project-discovery
Tipos técnicos de la API (request / response)	bun run api:sync
Casos de prueba y trazabilidad	/test-documentation
Orden de ejecución de un sprint	el STP de /sprint-testing
Una segunda skill sobre datos, API, E2E, dominio o infra	la skill de contexto que ya existe

Un "refrescá el contexto" genérico no dispara refresh-all: la skill pregunta qué modo.

El límite con project-discovery es el más importante: discovery genera los mapas de dominio e infraestructura y nunca toca los de datos, API o E2E, ni el plan maestro. Este deck cubre la otra mitad. El mapa de API además declara explícitamente lo que no es: no es un catálogo de endpoints, eso lo dan el spec OpenAPI y bun run api:sync.

Mapa · 3 de 16

Un modo por corrida, un gate por artefacto

Paso 1

Resolver el modo

primer token de los argumentos
o pregunta

→

Paso 2

Cargar su referencia

una sola · nunca una segunda
en la misma pasada

→

Paso 3

CREATE o UPDATE

falta: crea · existe: diff
y espera tu OK

Los modos (Mode routing del SKILL.md)

data

Mapa de datos

business-data-context

e2e · features

Mapa E2E

business-e2e-context

api

Mapa de API

business-api-context

test-plan

Master Test Plan

Epic QA Master Test Plan

Caminos adyacentes

refresh-all

Los cuatro en orden fijo

data → e2e → api → test-plan

context-skill

Skill propia del proyecto

.agents/skills/<aspect>-context/

coverage

Comportamientos vs tests

lista de brechas por riesgo

El modo sale del primer token de los argumentos: si coincide con un modo de la tabla, ese token es el modo y el resto se le pasa tal cual. features es sinónimo de e2e. Si no hay token reconocible, la skill pregunta. refresh-all nunca incluye context-skill ni coverage.

El gate · 4 de 16

Nunca pisa un mapa sin tu aprobación

El ahorro

Nunca regenera un mapa entero: el id estable de cada sección vuelve la actualización una edición de un bloque, y eso ahorra tokens.

Sin fuentes = desconocida

Una sección que no declara data-sources se reporta como unknown, nunca como vigente en silencio.

Dónde corta

Dependencia dura que falla u overwrite rechazado: para. Dependencia blanda que falta: Discovery Gap y sigue.

Este gate es el corazón de la skill y vale igual para los tres mapas. Para el Master Test Plan la lógica es la misma, pero la fuente de verdad es la descripción del Epic en Jira: si la caché local no aparece después de sincronizar, es CREATE; si aparece, UPDATE con diff y aprobación. Detalle del chequeo de vigencia: agentic-qa-core/references/business-context-maps.md §5.

Los mapas · 5 de 16

Un mapa es un HTML dentro de su skill

... <section id="flow-checkout" data-sources="src/orders/, db:orders" data-updated="YYYY-MM-DD"> <h2>Checkout</h2> <figure data-diagram="sequence" ...>…</figure> <p>Cada dato de la figura también está en el texto…</p> </section> ... <section id="discovery-gaps">…</section>

Ruta: .agents/skills/<slug>/references/<map>.html. Contrato completo: agentic-qa-core/references/business-context-maps.md.

Por qué en una skill

.context/ guarda lo que un script trae de una fuente de verdad. Un mapa es una síntesis de la IA que tiene que llegar sin pedirla. Un solo archivo, sin gemelo en markdown.

Cómo lo lee la IA

Nunca el HTML crudo: bun run context:map <slug>, --section <id> o --list. Un placeholder imprime un aviso y se trata como "no hay mapa".

Cómo lo ves vos

En el navegador o en bun run docs, servido desde la carpeta de su skill.

La primera línea es lo único que leen el lector, el updater y el doctor para distinguir un mapa generado de un placeholder. Las secciones son planas, nunca anidadas, y el id no cambia después del CREATE. La última sección siempre es discovery-gaps: "no pude verificar X" vale más que una respuesta inventada.

Modo data · 6 de 16

Cómo funciona el sistema, por dentro

Qué hace la IA

Agota las fuentes antes de escribir: la base en vivo (solo lectura), endpoints, backend, frontend, mapas de dominio e infra, dependencias. Sintetiza, no extrae: significado de negocio, no columnas.

Qué decidís vos

En UPDATE aprobás el diff por sección. En CREATE escribe sola tras el análisis.

Qué queda

El mapa en business-data-context y una revisión propuesta de las reglas de esa skill.

Sección	Contenido
overview	propósito, actores, figura general
entities	entidad · rol de negocio · por qué existe
flow-<slug>	cada flujo importante, de punta a punta
state-<entidad>	transiciones · evento · efectos
automatic-processes	triggers, crons y webhooks, con su porqué
integration-<svc>	impacto en datos y qué se rompe si cae
discovery-gaps	lo que no se pudo verificar

Capacidades: db para la base, diagrams antes de la primera figura.

La referencia lo llama el archivo de contexto más valioso del boilerplate: las demás skills de QA dependen de él, y el modo test-plan no arranca sin este mapa. Documenta todos los flujos importantes, sin tope de tres. Fuente: project-context/references/data.md.

Modo e2e (sinónimo features) · 7 de 16

Primero las personas y sus recorridos, después el catálogo

Personas

Son los roles que el código reconoce, con evidencia (enums, guards, UI condicional), no demografía inventada. Cada una trae su fila de permisos y la clave de cuenta de prueba que necesita (<ENV>_<ROLE>_EMAIL).

Recorridos

Se trazan por rutas: cada paso cita un archivo. Ramas de error, el paso donde cambian de manos plata o datos, y los pasos que necesitan algo externo (OTP, 2FA, CAPTCHA) marcados como tales. Un recorrido sin camino de error está incompleto.

Catálogo de features

Por dominio, con su tabla de reglas testeables BR-NNN (precondiciones, reglas, validaciones con el mensaje que ve el usuario, transiciones). Los IDs son estables entre regeneraciones: los tests los citan.

El resto del mapa

Matriz CRUD por entidad · inventario de UI (rutas, formularios, vistas, acciones) · integraciones · feature flags y trabajo en curso · relevancia QA (cobertura y riesgo) · discovery-gaps.

Lo que no repite

Los endpoints son un puntero por dominio a business-api-context. La máquina de estados apunta a business-data-context, nunca se redibuja acá.

Salida: business-e2e-context/references/business-e2e-map.html. features y el viejo nombre business-feature-map llevan a este modo. Los archivos legacy que un proyecto todavía tenga (mapa de features, personas y journeys del PRD, specs funcionales del SRS) se leen como entrada y nunca se borran. Fuente: project-context/references/e2e.md.

Modo api · 8 de 16

Cómo opera el negocio a través de la API

Un relato, no un catálogo

Modelo de permisos por niveles (público, autenticado, por rol, por dueño) anclado al código · entre 3 y 7 recorridos críticos trazados de cliente a respuesta · la arquitectura detrás de la API · integraciones con su modo de falla visible · referencias cruzadas a los otros dos mapas.

Gates

Mapas de datos o E2E ausentes: blando, avisa y sigue con un Discovery Gap. Sin spec OpenAPI y sin backend con rutas legibles: duro, para y pide un spec o bun run api:sync.

Fuera de su alcance

Pedido	Dueño
Catálogo completo de endpoints · tipos TS	bun run api:sync + spec
Matriz de casos por endpoint	/test-documentation
CRUD por entidad · inventario de UI	modo e2e
Esquemas, estados, reglas de negocio	modo data
Roadmap de testing por riesgo	modo test-plan

Cada sección hecha desde el contrato lleva openapi:<tag o path> en data-sources: así la próxima corrida detecta qué quedó viejo.

Si el sistema tiene más de siete recorridos críticos, la decisión de recortar se documenta en Discovery Gaps en vez de expandir en silencio. Nunca lee ni vuelca secretos reales: de la configuración solo mira los ejemplos. Salida: business-api-context/references/business-api-map.html. Fuente: project-context/references/api.md.

Modo test-plan · 9 de 16

Qué testear y por qué importa

Entradas

Mapa de datos: requisito duro, sin él para y pide el modo data. Mapa E2E: blando, avisa y lo anota como gap. Además, si existen: los riesgos HIGH de la evaluación de project-discovery, los presupuestos NFR del mapa de infra y el vocabulario del dominio.

El rubro de riesgo (interno)

Impacto de negocio × probabilidad de rotura × radio de impacto, cada uno de 1 a 3. El producto da CRITICAL (18 o más), HIGH (8 a 17), MEDIUM o LOW. Toda prioridad cita evidencia de los mapas.

Lo que escribe, en voz de QA senior

Mapa ejecutivo de riesgos y qué testear primero

Máquinas de estado con impacto financiero, legal u operativo

Silent killers: crons, webhooks y triggers que fallan sin que la UI lo muestre

Puntos de falla de integraciones y degradación aceptable

Cascada de dependencias entre flujos

Edge cases que se olvidan · checklist previo al release

Qué no está en el plan · Discovery Gaps

El MTP es la altitud de producto de la escalera de planificación: estrategia para todo el sistema. La profundidad por feature baja un escalón, al FTP de cada feature. No incluye diagramas de flujo, catálogos ni casos de prueba: esos viven en los mapas y en el TMS. Fuente: project-context/references/test-plan.md.

Modo test-plan · 10 de 16

El MTP se escribe en Jira, no en un archivo

Fuente y caché

Jira es la fuente de verdad. La copia local es .context/PBI/qa-artifacts/master-test-plan.md: gitignorada, la escribe la sync, nunca se edita a mano. Decisión: ADR-0007-mtp-in-jira.md.

Si no entra

Jira tiene un tope para la descripción. Si el ADF serializado pasa el límite del chequeo, para antes de escribir y te propone qué secciones bajan a qué FTP. Nunca trunca ni parte la sección.

MTP local viejo

Si un proyecto todavía tiene .context/master-test-plan.md, en CREATE ofrece sembrar el Epic desde ahí, con tu OK. Nunca borra el archivo.

Antes de cualquier operación de Jira carga /acli. El texto enriquecido pasa por el conversor de markdown a ADF de la skill acli. El tamaño se mide sobre el JSON ADF serializado, no sobre el texto visible: las tablas y las listas cortas son las que más crecen. Las mediciones están en el ADR-0007.

Modo refresh-all · 11 de 16

Los cuatro, en orden fijo y uno por vez

1 · data

Mapa de datos

el resto lo usa de entrada

→

2 · e2e

Mapa E2E

cruza con entidades y flujos

→

3 · api

Mapa de API

recorridos alineados a los dos

→

4 · test-plan

Master Test Plan

riesgo sobre los mapas

Un gate por paso

Cada referencia cierra su propia validación y su aprobación antes de que se cargue la siguiente. Nunca salta adelante.

Cuándo para

Una dependencia dura que falla o un overwrite que rechazás cortan la cadena ahí.

Solo si lo pedís

Nunca se infiere de "refrescá el contexto". Es el paso que recomienda /project-discovery al terminar, en una sesión limpia, porque consume muchos tokens.

Las dependencias blandas que faltan siguen siendo Discovery Gaps, exactamente como las define cada referencia. refresh-all no incluye context-skill ni coverage.

Modo context-skill · 12 de 16

Una skill de criterio para otro aspecto del proyecto

Qué crea

<aspect>-context/ con kind: context y gotchas.md. Es del proyecto: el updater nunca la entrega, pisa ni borra.

Cómo la construye

Siempre con skill-creator: borrador, pasada de descripción y tres prompts de prueba. Si falta, usa el template y lo avisa.

Antes de empezar

Lo que va a mirar tiene que existir. Datos, API, E2E, dominio e infra ya tienen skill: se señala la que existe.

El test de las tres preguntas

Se regenera? Es un dato? Queda en el mapa. Es criterio que tiene que llegar sin pedirlo? Regla en la skill, con fecha y cómo se midió. Sin medición no hay regla.

Validación

skills:check verde · skills:registry la suma a REGISTRY.md · fila en la tabla Project context skills de .agents/instructions/agent-project.md, con sus frases en triggers: (agent-skills-and-mcps.md se sincroniza y bun sync la pisaría) · nada copiado del mapa.

Después

Si sus fuentes se regeneran, ofrece UPDATE: suma reglas fechadas y mueve la falsa a "No longer true", sin borrarla.

El contrato de una skill de contexto está en agentic-qa-core/references/skill-scaffold.md §3 a §5. Nunca copia una tabla, una lista de entidades o de endpoints del mapa a la skill. Toda edición posterior la gobierna skill-refinement-protocol.md: nada se aplica solo. Fuente: project-context/references/context-skill.md.

Modo coverage · 13 de 16

Qué hace el producto que ningún test ejercita

collect · script

Comportamientos y tests

mapas (BR / FEAT) · manifest KATA
en producción · TMS

→

juicio · IA

Qué test cubre qué

exercises o weak, con una línea
de evidencia · riesgo del MTP

→

classify · script

Un bucket por comportamiento

ordena por riesgo · diff contra
la corrida anterior

Cuatro buckets

automated (un ATC en la rama de producción) · manual-only · weak (el test pasa por ahí, pero nada de lo que chequea fallaría) · uncovered. Las brechas son weak + uncovered.

Recalculable

Los juicios se guardan por id estable y vuelven en la próxima corrida; un juicio cuyo mapa o test cambió se marca viejo y se rejuzga primero. Así medís el avance corrida a corrida.

Lo que firmás vos

Una Tech Story de cobertura por brecha o por módulo, solo después de tu OK: propose es un dry run. El riesgo ordena; el ROI decide después, por Test.

Escribe solo en .session/project-context/coverage/ del checkout principal. Sin mapas generados, para con una nota; sin TMS, manual-only sale como unknown, nunca 0.

Es el paso de inventario del flujo discovery-driven: comportamiento en producción sin Story. No edita tests ni mapas y no entra en refresh-all. Script: bun run context:coverage collect, classify y propose. El veredicto weak y el nivel de riesgo son juicio de la IA con evidencia por fila; los buckets, el orden y el diff son aritmética. Fuente: project-context/references/coverage.md y discovery-driven-doctrine.md §1, §3 y §7.

Salvaguardas · 14 de 16

Lo que la skill nunca hace

Nunca	Qué hace en su lugar
Inventar un hecho de negocio	Lo que no verificó va a la sección de Discovery Gaps, obligatoria en cada salida.
Pisar un artefacto existente sin aprobación	Arma un candidato, muestra el diff y espera tu OK explícito.
Regenerar un mapa generado entero	Solo las secciones viejas, por su id.
Borrar un archivo legacy	Lo lee como entrada y lo cita en data-migrated-from.
Usar una capacidad que no está	Para en el punto de uso y nombra la capacidad (db, api-schema, diagrams) y cómo habilitarla.
Reescribir una regla de una skill de contexto	Después de escribir un mapa, revisa las reglas y gotchas de su skill y propone cambios.
Escribir prosa operativa en CLAUDE.md	Agrega el puntero en .agents/instructions/agent-project.md solo si falta. AGENTS.md no se toca.
Mezclar dos modos en una pasada	Carga una sola referencia; refresh-all las encadena una por vez.

Las capacidades salen de metadata.requires_capabilities y se resuelven por el sufijo del nombre de la herramienta, según preflight-gate.md §8: nunca un fallback silencioso. Para diagrams, la capacidad se resuelve por la presencia de la skill diagram-design, no por una herramienta MCP.

Invocación · 15 de 16

Cómo se invoca y dónde queda cada cosa

En los tres hosts

Claude Code: /project-context <modo>, por ejemplo /project-context data o /project-context context-skill <aspect>.

OpenCode y Codex: cargá la skill project-context, modo data (o el que corresponda).

Sin modo, pregunta. business-*-map y master-test-plan quedan solo como frases de disparo.

Lee

Código del SUT, base y contrato de API según el modo · otros mapas con bun run context:map · .agents/project.yaml · el Epic del MTP vía /acli.

Modo	Escribe
data	business-data-map.html en business-data-context
e2e	business-e2e-map.html en business-e2e-context
api	business-api-map.html en business-api-context
test-plan	Epic QA Master Test Plan en Jira · caché .context/PBI/qa-artifacts/master-test-plan.md
context-skill	.agents/skills/<aspect>-context/
coverage	gap-list.md en .session/project-context/coverage/ · Tech Stories en Jira solo con tu OK

Cada mapa va en references/ de su skill. Lista canónica: CONTEXT_MAP_SKILLS en cli/lib/context-maps.ts.

El primer token que coincide con un modo es el modo; lo demás se reenvía sin tocar al modo elegido. En context-skill, lo que sigue es el aspecto. Antes de cualquier escritura en Jira se carga /acli, y la caché del MTP se recarga con bun run jira:sync-issues get o con bun run context:hydrate.

Cierre · 16 de 16

Qué viene antes y después

Antes

bun sync entrega las skills de mapa, una vez, con su placeholder.
/project-discovery genera los mapas de dominio e infra y termina recomendando refresh-all en una sesión limpia, con sus riesgos HIGH como semilla del MTP.

Después

/test-framework-adaptation exige los mapas antes de adaptar.
/shift-left-testing y /sprint-testing chequean en su preflight que estén generados; un placeholder los manda a /project-discovery o al modo de esta skill.
/test-documentation baja el plan a casos.

Quién lee los mapas

Las skills de contexto (business-data-context, business-api-context, business-e2e-context): se cargan solas cuando una tarea toca su aspecto, leen su mapa con context:map y proponen editar una sección cuando una sesión observa algo que la contradice.

Lo que deja la skill

Mapas HTML con secciones fechadas y fuentes declaradas · un Master Test Plan en el Epic de Jira, leído de vuelta a la caché · Discovery Gaps explícitos · reglas de skills de contexto propuestas, nunca aplicadas solas.

Canon: .agents/skills/project-context/SKILL.md y references/ · contrato de mapas: agentic-qa-core/references/business-context-maps.md.

Fin del recorrido. La skill no corre workflows de testing: deja el contexto listo para que las skills de etapa lo usen. El mapa del slide 3 resume todo: resolver un modo, cargar su referencia, y pasar el gate de CREATE o UPDATE antes de escribir.