Agentic QA · Skill de workflow

/project-discovery

Convierte un código que QA todavía no conoce en un proyecto testeable: lee el repo objetivo, pregunta lo ambiguo y deja escritos el dominio y la infraestructura donde el resto de las skills los va a buscar.

Solo lectura sobre el repo objetivo Fases en orden, con tu OK entre cada una Lo no verificable va a discovery-gaps

Deck de la skill project-discovery: el onboarding de un proyecto bajo test. Es ingeniería inversa: describe lo que el sistema hace, nunca lo que producto quisiera que haga. Pulsá → para avanzar, S para modo presentador, O para overview, F para pantalla completa.

Decidir · 2 de 15

Es un proyecto que QA todavía no conoce?

Usala para

Arrancar con un producto nuevo: "set up this project", "onboard this repo", "connect to project".
Descubrir la arquitectura desde el código: "discover architecture".
Adoptar este boilerplate para testear una app.
Completar huecos de un proyecto ya documentado.
Refrescar sus dos mapas, sección por sección.

No es para esto: va a

Mapa de datos, de API o E2E, o el Master Test Plan	project-context
Adaptar KATA al stack del proyecto	/test-framework-adaptation
Escribir tests automatizados	/test-automation
Documentar casos en el TMS	/test-documentation
Correr suites	/regression-testing
Tipos exactos de la API desde OpenAPI	bun run api:sync

Un PRD o SRS "a futuro" tampoco: eso es crear producto, y discovery solo describe lo que ya existe.

La frontera con project-context es la que más se confunde. project-discovery genera solo dos mapas: el de dominio y el de infraestructura. Los mapas de datos, API y E2E y el plan de testing maestro son modos de project-context, que es dueño de su diff y de su aprobación.

Mapa · 3 de 15

Cuatro fases en orden, con un gate entre cada una

Antes de la Fase 1

Fase 0

Hay una sesión a medias?

.session/project-discovery/
resume · restart · abort

→

Repo objetivo

Fijar dónde vive

monorepo · repos hermanos
remoto: pedir el clon

→

Alcance

Elegir el escenario

lo confirmás vos
queda en plan.md

Las fases (cada una espera tu "Phase N complete")

Fase 1

Constitución

project-config.md
evaluación en agent-project.md
mapa business-domain-context

→

Fase 2

Arquitectura

mapa infra-context:
overview · architecture
external-services · nfr-*

→

Fase 3

Infraestructura

mapa infra-context:
backend · frontend
environments · ci-cd

→

Fase 4

Especificación

no escribe archivos
bun run jira:check

Después, en otra sesión

Handoff

project-context, modo refresh-all

data → e2e → api → test-plan

→

Luego

test-framework-adaptation

cablea KATA al stack

Nunca encadena fases sola: al cerrar cada una muestra lo que escribió y espera la confirmación. El handoff final tampoco se ejecuta en la misma sesión, porque generar los mapas de negocio necesita su propio presupuesto de tokens y su propio ciclo de aprobaciones.

Antes de la Fase 1 · 4 de 15

Primero, dónde está el código y dónde quedó la sesión

El repo objetivo (nunca este boilerplate)

Layout	Qué se declara
Monorepo	Una ruta. Se detecta por pnpm-workspace.yaml, turbo.json, nx.json, lerna.json o un package.json raíz sin dependencias propias.
Repos hermanos	Una ruta por repo. La Fase 1 corre una vez por repo y todo se une en un project-config.md, sin intercalar.
Remoto	URL y rama, y te pide clonarlo. Desde una URL no se descubre nada: hace falta el código en disco.

Si la ruta es ambigua, la Fase 1 queda bloqueada hasta resolverla.

Fase 0 · retomar

Si existe .session/project-discovery/progress.md, te muestra alcance, repo, última fase cerrada, la siguiente y los gaps abiertos. Vos elegís resume, restart o abort.

Por qué importa

Un onboarding completo lleva horas. Sin retomar, la próxima sesión rehace la Fase 1 y vuelve a preguntarte rutas que ya confirmaste. restart archiva lo anterior en .session/.archive/.

La ruta resuelta queda registrada en la sección Repositories de .context/project-config.md durante la Fase 1, y cada referencia posterior al repo objetivo apunta a esa ruta.

Alcance · 5 de 15

Mismas fases, distinta profundidad

Escenario	Fases	Después	Peso
Onboarding desde cero	1 → 2 → 3 → 4	project-context modo refresh-all, y luego test-framework-adaptation	Pesado: un subagente por fase para leer el código
Adopción del boilerplate	1 → 3; la 2 y la 4 se saltean solo si sus artefactos ya existen	project-context para los mapas que falten	Medio: la Fase 1 siempre completa
Brownfield	2 → 3 → 4, solo los huecos	project-context para los mapas viejos	Liviano: sesión principal
Refresco de contexto	Fase 1 o Fases 2-3 en UPDATE; Fase 4 si cambió el backlog	Mapas de negocio o MTP: el modo de project-context que corresponda	Mínimo: casi siempre un handoff

Ante la duda

Onboarding desde cero. El alcance se confirma con vos antes de la Fase 1 y queda escrito en .session/project-discovery/plan.md.

El handoff no es una fase

El plan termina en la Fase 4. project-context refresh-all se anota como paso siguiente, no como parte de discovery.

En la adopción del boilerplate la Fase 1 corre entera porque el mapa de dominio es requisito de test-framework-adaptation. Antes de pasar a esa skill hay que verificar los archivos en disco.

Fase 1 · 6 de 15

Constitución: quién, qué y por qué

1 · Conexión

Repos, stack, entornos, herramientas

→ .context/project-config.md

→

2 · Evaluación

Madurez de testing, docs, calidad, CI/CD, riesgos

→ ## Project Assessment (Phase 1)
en .agents/instructions/agent-project.md

→

3 · Modelo de negocio

Problema, usuarios, propuesta de valor

→ overview · business-model

→

4 · Glosario

Entidades, etiquetas de UI, enums

→ term-<slug> · enumerations
discovery-gaps

Ningún sub-paso arranca hasta que existe la salida del anterior. Los pasos 3 y 4 escriben el mapa de business-domain-context.

Pregunta de a una

Primero el repo, después el stack, después los entornos. Detecta lo que puede desde package.json, .env.example o los workflows antes de preguntarte.

Riesgos HIGH

Sin tests o con un secreto hardcodeado: fila en ### Identified Risks, con la ruta, nunca el valor. Viajan al cierre como semilla del Master Test Plan.

Gate

bun run context:map business-domain-context --list muestra secciones y ningún aviso de placeholder, project-config.md tiene ## Tech Stack y ## Environments, y vos decís "Phase 1 complete, continue".

La evaluación usa escalas simples: madurez de testing de 0 a 4, estado de documentación y madurez de CI/CD. No se escribe un archivo de riesgos aparte. Si se juntan sin tests, secretos hardcodeados y sin CI, el avance se frena: hay que resolver los secretos y re-evaluar antes de la Fase 2.

Fase 1 · 7 de 15

El mapa de dominio: el vocabulario de todo QA

Una sección term-<slug> por entidad (ejemplo)

Esa fila es el puente entre cómo habla el código y cómo habla el negocio. Las etiquetas salen de los archivos i18n que se publican, no del JSX.

Atributos, relaciones y estados no van acá: la sección apunta a business-data-context o deja el gap mientras ese mapa sea placeholder.

business-model

El Business Model Canvas como tabla Block | Finding | Found in | Confidence. Un bloque sin evidencia dice "Unknown" y va a discovery-gaps. Copy de marketing baja la confianza.

Quién lo usa

/sprint-testing lo carga para planificar el ATP y los casos; /test-documentation, para nombrar los TCs. Por eso el glosario nunca se saltea.

Schema antes que ORM

Si hay migraciones y modelos ORM, mandan las migraciones: el ORM se desvía del esquema vivo.

Los valores de la tabla son ilustrativos (la skill usa user como Customer y order como Purchase de ejemplo). Cada entidad central del esquema tiene su sección term-, y cada enum su tabla en enumerations, con el valor de la constante del código y no el texto libre.

Fase 2 · 8 de 15

Arquitectura: cómo está construido, leído del código

Sección de infra-context	Qué lleva
overview	Patrón, tabla del stack, forma del deploy.
architecture	Componentes, flujo de datos, flujo de login, base de datos a nivel arquitectura, seguridad. Suele llevar la figura principal.
external-services	Servicios de terceros, su punto de integración y el nombre (solo el nombre) de su variable de entorno.
nfr-<slug>	Una por categoría con evidencia: nfr-performance, nfr-security, nfr-reliability…

La API no se documenta acá

Solo registra dónde está la spec en project-config.md. Los tipos son de bun run api:sync; el ángulo de negocio, de project-context modo api.

Números con evidencia

"P95 < 500ms" sin una prueba que lo respalde es un gap, no un requisito.

ADRs

Una decisión de arquitectura de tests difícil de revertir (runner, aislamiento, fixtures y datos, auth en tests, contrato de selectores, sharding en CI) se vuelve .context/ADR/ADR-NNNN-<slug>.md, en Proposed. La aceptás vos.

Gate: bun run context:map infra-context --list muestra architecture y al menos una nfr-, la fuente del contrato de API está en project-config.md, y vos decís "Phase 2 complete".

Personas, journeys y specs funcionales tampoco son de esta fase: los arma project-context modo e2e. Si no hay spec de OpenAPI, se anota en discovery-gaps y se recomienda correr project-context modo api cuando termine discovery; nunca se escribe un contrato de API a mano.

Fase 3 · 9 de 15

Infraestructura: que el proyecto corra para testear

Antes, la página /qa del sistema, si la publica

Se lee primero, antes de detectar el stack. Es una pista: cada dato se contrasta con el código y la configuración que la fase lee igual, y si no coinciden gana el código y el desacuerdo va a discovery-gaps. No se copia ningún valor a un archivo versionado. Si la página no existe, no es un hueco de discovery.

backend

Runtime, scripts, dependencias, variables de entorno (requeridas, opcionales, de servicios externos), base de datos y migraciones, receta local de instalación y arranque, y el flujo de login real: endpoint, payload, qué devuelve y dónde vive la sesión.

frontend

Build y modo de salida, variables públicas (un secreto con prefijo público es un hallazgo de seguridad), routing, estado, cliente de auth y la estrategia de test IDs, con data-testid como preferida.

environments

Matriz de entornos (URL, rama, auto-deploy, aprobación), variables por entorno, dónde se guardan los secretos (nunca sus valores), monitoreo y cómo se hace rollback.

ci-cd

Workflows, triggers, deploy, IaC o "Not present", y los comandos exactos que corre CI: mandan sobre los scripts locales, que pueden desviarse.

Detecta y después confirma: nunca te pregunta "qué stack es?". Con docker-compose.yml, el inventario de servicios sale de ahí antes que del código.

En un monorepo corre por paquete (backend-<pkg>, frontend-<pkg>); environments y ci-cd quedan a nivel proyecto. Gate: las cuatro secciones listadas y tu "Phase 3 complete".

El flujo de login en backend es el insumo más importante para test-framework-adaptation: le da un contrato concreto para la autenticación de los tests. Si el proyecto no tiene ningún framework de tests, se documenta como gap y no se instala nada en el repo objetivo.

Fase 4 · 10 de 15

Especificación: probar que el backlog responde

1

Tracker identificado

de project-config.md
o una pregunta

→

2

Una lectura

Get Issue
{{PROJECT_KEY}}-1

→

3

Project key

.agents/project.yaml
bun run agents:setup

→

4

Catálogo de campos

bun run jira:check
(antes jira:sync-fields si falta)

→

5

Jerarquía declarada

.agents/jira-required.yaml
work_types · sync:

No escribe ningún archivo

Ni .context/PBI/README.md ni los templates/. La receta de acceso ya existe; la fase verifica que funcione para este proyecto.

No copia el backlog

Jira es la fuente de verdad. El PBI de cada ticket lo sincroniza después /sprint-testing con bun run jira:sync-issues, como caché de solo lectura.

Credenciales

ATLASSIAN_EMAIL y ATLASSIAN_API_TOKEN en .env. El host vive en issue_tracker.atlassian_url de .agents/project.yaml.

Gate: bun run jira:check en verde, o el motivo (sin acceso, sin token, otro tracker) anotado en ## Discovery Gaps de project-config.md. Vos decís "Phase 4 complete".

Jira se opera con /acli y GitHub Issues con gh issue; otro tracker no tiene skill dedicada y queda como gap. Si una muestra de stories recientes viene con ACs vacíos, eso también es un gap: es la oportunidad de shift-left para QA. Nunca se inventan ACs, IDs de campos ni nombres de estados.

Mapas · 11 de 15

Un mapa es HTML dentro de su skill

Dónde vive y cómo se lee

.agents/skills/<slug>/references/<map>.html, sin copia en .context/ ni gemelo markdown. Se lee con bun run context:map <slug> (o --section <id>, --list), nunca el HTML crudo. bun run docs lo muestra en "Mapas de contexto".

Markdown viejo

Los .md legacy de .context/ se leen como insumo y se citan en data-migrated-from. Nunca se borran.

Figuras

Con la skill diagram-design (capacidad diagrams). Si falta, frena y te dice cómo instalarla.

Cada sección del mapa es un section plano con id estable, data-sources y data-updated; la última siempre es discovery-gaps. El chequeo de vigencia mira si los paths de data-sources tuvieron commits desde data-updated, si cambió el contrato de la API o el esquema. Una sección sin fuentes se informa como unknown, nunca como vigente.

Salvaguardas · 12 de 15

Lo que nunca hace

#	Regla
P1	Inventar entidades, flujos o requisitos que no estén en el código o el PRD. Lo no verificado va a discovery-gaps.
P2	Saltear la Fase 1 en un arranque desde cero: lo que viene después queda sin base.
P3	Llenar los mapas de datos, API o E2E. Solo genera business-domain-context e infra-context.
P4	Mezclarse con test-framework-adaptation en la misma sesión: sus límites de escritura son distintos.
P5	Refrescar los mapas de otra skill. Los suyos, sección por sección, nunca enteros.
P6	Saltear el glosario: /sprint-testing y /test-documentation lo cargan como precondición.
P7	Inventar IDs de campos o estados de Jira / Xray: se sincronizan con bun run jira:sync-fields --force y se citan como {{jira.<slug>}}.

Repo objetivo intacto: no escribe ni instala nada ahí.

Sin secretos: nombra la clave de .env o la ruta, nunca el valor.

Sin auto-encadenar: cada fase espera tu confirmación.

Los anti-patrones del SKILL.md, más tres reglas compactas. Antes de usar una capacidad declarada (db, api-schema, diagrams) corre el chequeo en el punto de uso: si ninguna herramienta disponible la provee, frena y nombra la capacidad y cómo habilitarla, sin caer en silencio a otra herramienta.

Entradas y salidas · 13 de 15

Lee mucho, escribe en pocos lugares

Lee

El repo objetivo: código, README.md, PRD si lo hay.
Lo que ya se descubrió: bun run context:map <slug> --list, .context/project-config.md, markdown legacy.
.agents/project.yaml y .env.example.
kata-manifest.json, para registrar los huecos con coherencia.
La base de datos (solo lectura) y la spec de OpenAPI, si están.
Docs de negocio que le pases (Confluence, Notion, wikis).

Escribe solo

.context/project-config.md
El bloque ## Project Assessment (Phase 1) de .agents/instructions/agent-project.md
.context/ADR/, en Proposed
El mapa de business-domain-context y el de infra-context

Y su propio estado

.session/project-discovery/plan.md y progress.md, una entrada por fase cerrada. Al terminar la Fase 4 se archivan.

Capacidades declaradas en el frontmatter: db, api-schema y diagrams, cada una con su chequeo en el punto de uso. Las consultas a la base son de solo lectura durante discovery. Si la sesión se rechaza en un gate, no se archiva: queda lista para retomar desde ese gate.

Handoff · 14 de 15

Al terminar: el siguiente paso y lo que propone

Próxima skill, en una sesión limpia

project-context modo refresh-all: data → e2e → api → test-plan, cada una con su aprobación. Los riesgos HIGH de la Fase 1 van como semilla del Master Test Plan.

Propone criterio, no lo escribe

Una línea por cada skill de contexto con mapa: el criterio que una sesión necesitaría (un término que el equipo y el código nombran distinto, un comportamiento que solo pasa en un entorno). Se vuelve regla fechada recién sobre un mapa aprobado. "No candidate yet" vale.

Propone otras skills de contexto

Aspectos del proyecto que merecerían su propia <aspect>-context. Las crea después project-context modo context-skill, con skill-creator.

Antes de test-framework-adaptation

Mapa de business-domain-context generado	Fase 1
Mapa de infra-context con backend y frontend	Fases 2-3
.context/project-config.md	Fase 1
Mapa de business-data-context generado	project-context
Fuente de la API: tipos, spec o mapa de API	api:sync o project-context
.env.example	proyecto

Lo que falta vuelve a su fase o al modo de project-context que lo genera.

El bloque de cierre se imprime tal cual al confirmar la Fase 4: lista lo poblado con los comandos para leerlo, el resultado de jira:check, la próxima skill, la semilla de riesgos y las propuestas. No encadena el handoff en la misma sesión.

Cierre · 15 de 15

Invocación y handoffs

Cómo se invoca

Claude Code: /project-discovery.
OpenCode y Codex: cargá la skill project-discovery.

No tiene modos: el alcance se elige en la conversación. También se activa con "onboard this repo" o "set up this project".

Antes y después

/agentic-qa-onboard te deriva acá ante un repo nuevo.
Después: project-context (refresh-all) y luego /test-framework-adaptation.
Si preguntás por qué el proceso tiene esta forma: iql-context.

Quién consume los mapas

/sprint-testing: planifica con el glosario.
/test-documentation: nombra los TCs.
/test-framework-adaptation: toma el flujo de login y el stack.

Lo que deja la skill

.context/project-config.md · la evaluación en .agents/instructions/agent-project.md · el mapa de dominio y el de infraestructura, legibles con bun run context:map · ADRs en Proposed · una lista honesta de discovery-gaps · el backlog verificado.

Canon: .agents/skills/project-discovery/SKILL.md y sus references/ (una por fase). Anatomía de los mapas: agentic-qa-core/references/business-context-maps.md.

Fin del recorrido. El mapa del slide 3 resume todo: retomar si hay sesión, fijar el repo y el alcance, recorrer las fases con tu confirmación y entregar el resto a project-context en una sesión nueva.