Agentic QA · Categoría de skills
Las context skills: skills que cambian lo que el agente sabe sobre un aspecto del producto o del método, nunca lo que hace después. Llegan sin que nadie las pida y se leen por partes.
El principio · 2 de 17
La línea divisoria
.context/ guarda lo que un script trae de una fuente de verdad, más lo poco que este repo es dueño. Lo que una IA sintetiza vive en una skill.
Por qué una skill
Ese conocimiento es autoral (lo escribe una IA, pero lo escribe) y tiene que llegar sin que nadie lo pida. Una skill se carga sola por su description; un archivo suelto en .context/ espera a que alguien lo abra.
El principio · 3 de 17
La pregunta
Dos sesiones competentes lo escribirían distinto? Sí: es juicio, va como regla fechada en ## Rules o en references/gotchas.md. No: es un hecho, va al mapa (o a la caché) y nunca al SKILL.md.
Ejemplo de juicio
"Las órdenes se borran en forma lógica: un conteo sin deleted_at IS NULL está mal." El mapa describe la tabla; la regla enseña a leerla.
Cada regla, medida
fecha · regla · measured: cómo. Sin medición no hay regla: la idea va a Engram.
Cita, nunca copia
Una context skill que repite un hecho de .context/ es una segunda fuente de verdad y no pasa review. Nombra el path o el comando, y el lector va a buscarlo.
El mapa es la única copia
El mapa HTML no duplica nada: es la única copia de esa síntesis. Los markdown viejos son entrada del generador.
La lint lo vigila
STALE-PATH es estricta acá: todo path de .context/ citado tiene que existir. Solo .context/PBI/ queda exento.
Anatomía · 4 de 17
Contrato: agentic-qa-core/references/skill-scaffold.md §1, §2 y §4. KIND-SUFFIX exige el sufijo -context para el kind context, y al revés.
Secciones obligatorias del cuerpo
| What this skill knows | un solo aspecto |
| Sources of truth | lo que cita, con su rol |
| Rules | juicio, cada regla fechada |
| Not here | qué pertenece a otra parte |
Alcance de escritura
metadata.writes solo existe en una context skill y solo puede nombrar su propio references/. Lo controla CONTEXT-WRITES, que además exige refresh.md y prohíbe cualquier tag de escritura en Jira.
La categoría · 5 de 17
Con mapa · entregadas por upstream
Llegan como placeholders y cada una guarda un mapa HTML del sistema bajo prueba. La lista es CONTEXT_MAP_SKILLS en cli/lib/context-maps.ts, con el generador de cada mapa.
El índice del método
iql-context: la metodología IQL de este repo. Sin mapa y sin escritura propia. Upstream la sincroniza y cada proyecto la adapta por dos costuras (slide 14).
Del proyecto
Cualquier otro <aspect>-context (un billing-context, un auth-context) es del proyecto por construcción. Upstream nunca lo entrega, nunca lo pisa, nunca lo borra.
| Ejemplo con mapa | Qué sabe | Quién genera su mapa |
|---|---|---|
| business-data-context | entidades, estados, triggers, jobs, integraciones | project-context modo data |
| business-api-context | grupos de endpoints, auth, semántica de errores | project-context modo api |
| business-domain-context | el negocio y el significado de cada término | project-discovery Phase 1 |
La tabla muestra ejemplos. La lista completa y vigente: CONTEXT_MAP_SKILLS para las que llevan mapa y .agents/skills/REGISTRY.md para todas las skills.
El mapa · 6 de 17
Entrega
Placeholder
bun sync deja la carpeta
si falta
CREATE
El generador lo escribe
todas las secciones, una vez
markdown viejo como entrada
Uso
Se lee por el lector
context:map <slug>
--section <id>
Cuando la realidad lo contradice
Una sección
La skill propone
evidencia · antes / después
se aplica con aprobación
Varias secciones
El generador en UPDATE
chequeo de staleness
diff por sección · aprobación
Una figura
Se redibuja sola esa
un <figure>, nada más
Lo que no pasa nunca
Regenerar
El mapa entero
ningún camino lo hace
Borrar
Los markdown viejos
quedan como entrada
Renombrar
El id de una sección
es el ancla de edición
El mapa · 7 de 17
Sin generar, la línea 1 dice <!-- placeholder: ... -->. El lector, el updater y el doctor solo miran esa línea.
Secciones planas
Una por unidad de hecho (una entidad, un flujo, un journey, un término, un NFR), nunca anidadas. El id no cambia después del CREATE. data-sources dice de dónde salió: paths del repo, db:, openapi:, route:.
El texto manda
Ningún hecho vive solo dentro de un diagrama. Las figuras las dibuja diagram-design (capability diagrams); si falta, se frena.
Última sección
discovery-gaps: "no pude verificar X" vale más que una respuesta inventada.
Lectura · 8 de 17
| Comando | Para qué |
|---|---|
| bun run context:map <slug> | el mapa entero como texto |
| bun run context:map <slug> --section <id> | una sección, cuando el trabajo toca una entidad, un journey o un término |
| bun run context:map <slug> --list | el índice: id · fecha · fuentes, para un chequeo de staleness |
Así imprime una sección (ejemplo ilustrativo).
Placeholder no es "sistema vacío"
Imprime un aviso con su generador y sale con código 0: se trata como "no hay mapa".
Por qué un lector
El SVG inline es casi todos los bytes y ningún hecho. scripts/context-map.ts quita SVG, estilos, scripts y el head, y reduce cada figura a una línea. La IA paga solo el texto.
Mantenimiento · 9 de 17
| Señal declarada | Vencida cuando |
|---|---|
| src/orders/ | hay commits en ese path desde data-updated (git log --since=<fecha> -- <path>) |
| openapi:<tag> | el contrato cambió desde la fecha (salida de bun run api:sync, o el git log del spec) |
| db:<tabla> | una migración posterior, o la DB muestra una columna o constraint que la sección no describe |
| route:<path> | el archivo de la ruta o de la página cambió |
| sin fuentes | se reporta como unknown, nunca como vigente en silencio |
Dos caminos, nunca mezclados
Una sección contradicha por algo que vio una sesión: la skill propone la edición. Varias vencidas, o una entidad que el mapa no tiene: el generador en UPDATE regenera solo esas y muestra el diff por sección.
Señales propias del aspecto
Cada skill con mapa agrega las suyas en su references/refresh.md, que es del proyecto. Por ejemplo, la de datos suma cron:<job> y webhook:<event>.
Mantenimiento · 10 de 17
1
Ubicar
--list, después
--section <id>
2
Evidencia
medida: query, request,
archivo en un commit
3
Proponer
al usuario, o al conductor
si es un worker
4
Aplicar con OK
releer, editar un bloque,
actualizar data-updated
5
Verificar
--section <id> imprime
el texto nuevo
El mensaje, tal como lo define references/refresh.md.
El silencio no aprueba
Solo un sí aplica la edición. Sin evidencia no hay propuesta. Un subagente de una sola vuelta pone la propuesta en su reporte en lugar de aplicarla.
Dónde escribe
Solo bajo su propio references/. Nunca Jira, nunca .context/, nunca otra skill, nunca código del producto. Y nunca corre una etapa del proceso.
Carga · 11 de 17
En la conversación principal
Se dispara por su description, aunque nadie diga "mapa": una pregunta sobre un status code raro trae a la de API.
En un subagente
El Skill Resolver inyecta solo las context skills cuyo aspecto toca el despacho, nunca todas, y para un mapa inyecta el comando (context:map <slug> --section <id>), nunca el path del HTML. Sin aspecto nombrado, ninguna.
| Si el despacho... | recibe (ejemplos) |
|---|---|
| siembra datos, escribe SQL, sigue una entidad | business-data-context |
| tests de API, endpoints, auth, status codes | business-api-context |
| tests E2E, un smoke, un flujo de usuario | business-e2e-context |
| nombra conceptos: un ATP, un caso, un AC | business-domain-context |
| stack, entornos, CI, auth en tests | infra-context |
| explica o aplica la metodología | iql-context |
| toca el aspecto de una skill propia | <aspect>-context |
Entrega · 12 de 17
| Qué | Qué hace el updater | Dueño |
|---|---|---|
| Una skill de CONTEXT_MAP_SKILLS | entrega la carpeta entera una vez, si falta; después nunca la pisa ni la borra | el proyecto, desde la entrega |
| Su mapa sin generar, o un markdown viejo al lado | una fila informativa, nunca bloqueante, en el reporte de cierre (la tabla por superficie, en la página local y en la terminal); bun run setup:doctor la repite como aviso | el proyecto |
| Cualquier otro <aspect>-context | nunca lo entrega, nunca lo pisa, nunca lo borra, aunque upstream publicara uno con el mismo slug | el proyecto, por construcción |
| iql-context (cuerpo y referencias) | lo sincroniza tal cual; una edición directa sale como fila de paridad | upstream |
| su project-overrides.md | lo entrega una vez si falta; después nunca lo pisa | el proyecto |
Por qué así
El mapa adentro de una skill entregada es la síntesis de ese proyecto: pisarlo en un sync borraría trabajo que costó miles de tokens. La regla vive en isProjectLocalSkillPath (cli/lib/updater-core.ts) y la excepción de entrega única, en cli/lib/context-maps.ts.
Crear · 13 de 17
Propone
project-discovery
al cierre: una línea por aspecto
nunca un archivo
Precondición
Lo que cita existe
el mapa o el path
antes que la skill
Crea
project-context · context-skill
siempre a través de
skill-creator
Gate
Validación
skills:check · skills:registry
fila en .agents/instructions/agent-project.md
Análisis antes de escribir
Leer la fuente entera, listar dónde una sesión competente la leería mal (borrado lógico, campos derivados, estados que la API y la UI nombran distinto) y pasar cada candidato por las tres preguntas.
CREATE y UPDATE
Si la carpeta no existe, la escribe después del análisis. Si existe, muestra el diff y espera. Las reglas viejas no se reescriben: se agregan nuevas con fecha, y una contradicha pasa a "No longer true".
Lo que no crea
Un pedido de data-context, api-context, glossary-context o infra-context se responde señalando la skill que ya viene, nunca con una segunda skill sobre el mismo aspecto.
Cómo se invoca
Claude Code: /project-context context-skill <aspect>. OpenCode y Codex: cargá la skill project-context, modo context-skill, y nombrá el aspecto. refresh-all nunca incluye este modo.
El índice del método · 14 de 17
Qué sabe
Por qué el proceso QA tiene la forma que tiene: fases, etapas con nombre (nunca con número), la escalera de artefactos (de MTP a ATR), dónde se aplica cada invariante y el contrato agéntico.
Qué no hace
Nunca corre una etapa (eso es de las skills de workflow) y no sabe nada del producto bajo prueba.
Web y repo en desacuerdo
Las skills aplican la doctrina de agentic-qa-core/references/. Esta skill da las dos lecturas y no "arregla" ninguna.
Cómo la adapta un proyecto (dos costuras)
| Costura | Qué va ahí |
|---|---|
| .agents/project.yaml → qa.methodology | valores: etapas que corre, gates strict o light, perfil de ejecución |
| references/project-overrides.md | prosa: una etapa corrida distinto, un artefacto renombrado, un gate colapsado, vocabulario local |
| El cuerpo y las demás referencias | ninguna: se sincronizan tal cual |
Lo que dice project-overrides.md gana sobre el índice, solo para ese proyecto.
Para personas · 15 de 17
Sin copia en docs/
bun run docs sirve cada mapa desde la carpeta de su skill, bajo la carpeta virtual mapas-de-contexto/. El portal y la IA leen el mismo archivo.
Un mapa sin generar
Aparece en el portal con la indicación "Sin generar todavía: ejecuta" seguida del generador de esa skill.
Ni gemelo en markdown
No hay versión markdown del mapa: el gemelo es siempre el que se desactualiza.
Salvaguardas · 16 de 17
| C1 | Leer el mapa HTML crudo: siempre por bun run context:map. |
| C2 | Responder sobre un placeholder como si el sistema estuviera vacío. |
| C3 | Regenerar un mapa entero, o reescribir una sección que nadie contradijo. |
| C4 | Cambiar el id de una sección: una entidad renombrada es una sección nueva más una línea en discovery-gaps. |
| C5 | Copiar contenido del mapa o de .context/ dentro de su SKILL.md. |
| C6 | Escribir fuera de su propio references/: ni Jira, ni .context/, ni otra skill, ni código del producto. |
| C7 | Aplicar una edición sin un sí explícito, o proponerla sin evidencia medida. |
| C8 | Tomar una sección más vieja que el código como respuesta: es una hipótesis a verificar. |
| C9 | Publicar upstream una context skill del sistema bajo prueba. |
Cierre · 17 de 17
Cómo se usan
No se invocan como un workflow: se cargan solas por su description en los tres hosts. Para pedirlas a mano, en Claude Code /<aspect>-context; en OpenCode y Codex, cargá la skill <aspect>-context. No tienen modos.
Quién escribe sus mapas
/project-discovery: el de dominio (Phase 1) y el de infraestructura (Phases 2-3).
/project-context: los de datos, API y E2E (modos data, api, e2e), y las skills nuevas (modo context-skill).
Quién las lee
Las skills de workflow y sus subagentes, cada vez que tocan el aspecto: /shift-left-testing, /sprint-testing, /test-automation, /test-framework-adaptation y el resto, según el Skill Resolver.
El canon
agentic-qa-core/references/skill-scaffold.md §3 (el principio) · business-context-maps.md (el mapa) · skill-resolver.md (quién las carga) · cli/lib/context-maps.ts (la lista) · scripts/context-map.ts (el lector) · .agents/skills/REGISTRY.md (todas las skills).