Lectura e ingesta de historias y bugs
Estas cinco skills son el punto de entrada de casi cualquier flujo de QA: normalizan una
historia de usuario o un bug reportado — venga de un archivo local, de Jira o de Azure DevOps — en
una estructura de datos común que el resto de las skills puede consumir sin preguntarse de dónde
salió. La quinta, lippia-neo-read-test-plan, hace lo mismo con un plan de pruebas ya escrito en
disco.
Ninguna escribe en disco cuando la fuente es remota
El contenido traído de Jira/Azure DevOps se mantiene siempre en memoria, nunca se persiste en el directorio local de historias.
lippia-neo-read-user-story
Cuándo usarla
Al iniciar un flujo de QA sobre una historia de usuario. Recibe una referencia — un path local
a un .md o la URL de un ticket (Jira / Azure DevOps) — la resuelve automáticamente y extrae
el resumen, los criterios de aceptación, la URL de la app, las credenciales de prueba y las
funcionalidades clave a probar. Es el punto de entrada estándar de cualquier flujo basado en
historias (el análogo de lippia-neo-read-bug-report para bugs).
{
"input": {
"user_story": "user-stories/PA-US-02.md"
}
}
| Input | Tipo | Descripción |
|---|---|---|
input.user_story |
Requerido | Path local a un .md o URL de un ticket remoto; nunca se hardcodea. Un path se lee siempre del disco (probando también relativo a paths.user_stories_storage.local_path); una URL solo se procesa si su proveedor coincide con paths.user_stories_storage.cloud_provider_mcp de qa-stack.yaml y su host con la instancia configurada en .mcp.json — si no, la skill se detiene. |
input.user_story_ref |
Opcional | Alias explícito de la referencia, si no se usa input.user_story. |
input.identifier |
Opcional | Identificador ya resuelto por quien la invoca; tiene prioridad sobre el us_id derivado de la historia. |
input.jira_content / input.jira_source_url |
Opcional | Contenido ya traído por lippia-neo-fetch-user-story con provider: jira (típico de un plan M2/M4 que ya resolvió la fuente); si viene, tiene prioridad sobre input.user_story. |
input.azure_content / input.azure_source_url |
Opcional | Mismo criterio, para contenido ya traído por lippia-neo-fetch-user-story con provider: azure-devops. |
Salida
| Campo | Descripción |
|---|---|
us_id / identifier |
Identificador corto de la historia, y su alias normalizado. |
summary |
Resumen de la historia. |
acceptance_criteria |
Lista de criterios de aceptación. |
app_urls |
URL(s) de la app bajo prueba. |
credentials |
Credenciales de prueba referenciadas. |
key_features |
Funcionalidades clave a probar. |
source_kind |
local_path | jira | azure-devops. |
user_story_path / source_url |
Ruta local o URL del ticket de origen, según source_kind. |
can_continue |
true si hubo contexto suficiente para resumir con confianza; null si no (nunca false). |
Se encadena con
Primer paso de cualquier flujo basado en historia (lippia-neo-meta-run-user-story-e2e, planes M2/M4). Para URLs
remotas, despacha a lippia-neo-fetch-user-story (Jira o Azure DevOps, según la fuente). Sigue con
lippia-neo-create-test-plan → lippia-neo-run-manual-testing → lippia-neo-generate-test-suite → lippia-neo-run-and-heal →
lippia-neo-write-test-report.
lippia-neo-fetch-user-story
Subskill de lippia-neo-read-user-story
No hace falta invocarla directamente: invocás lippia-neo-read-user-story y esta subskill se elige sola cuando le pasás la URL o la clave/ID de un ticket de Jira o de Azure DevOps.
Cuándo usarla
Cuando el trabajo de QA debe arrancar desde un ticket de la herramienta de gestión — un issue de
Jira Cloud o un work item de Azure DevOps — en vez de un archivo .md local. Trae el ticket vía
el MCP de la herramienta (jira o azure-devops) y lo devuelve estructurado en memoria, listo
para que lippia-neo-read-user-story (o lippia-neo-meta-run-user-story-e2e)
lo consuma directo. Acepta clave o ID desnudo (TS-42, 1234), URL del ticket, o el argumento del
slash command: /lippia-neo-fetch-user-story <clave-ID-o-URL>.
Es una sola skill para las dos herramientas: el procedimiento común (resolver la herramienta,
mapear campos, enmascarar datos sensibles, armar el contenido canónico) vive en su SKILL.md, y lo
propio de cada herramienta — qué MCP usar, cómo leer el identificador, de dónde salen los criterios
de aceptación — en un archivo de referencia (references/jira.md, references/azure-devops.md) que
lee antes de la primera llamada al MCP.
{
"input": {
"story_ref": "https://tu-sitio.atlassian.net/browse/TS-42"
}
}
{
"input": {
"story_ref": "https://dev.azure.com/tu-org/tu-proyecto/_workitems/edit/1234"
}
}
{
"input": {
"story_ref": "1234",
"provider": "azure-devops"
}
}
| Input | Tipo | Descripción |
|---|---|---|
input.story_ref |
Requerido | Clave, ID o URL del ticket (TS-42, 1234, o la URL de Jira / Azure DevOps); la skill extrae el identificador canónico. |
input.provider |
Opcional | jira | azure-devops. Si no viene, la herramienta se detecta por la forma de la URL; con una clave o ID suelto, se toma de paths.user_stories_storage.cloud_provider_mcp de qa-stack.yaml. |
input.project |
Opcional | Solo Azure DevOps: override del Team Project; si no viene, usa azure_devops.default_project de qa-stack.yaml y, en su defecto, AZURE_DEVOPS_DEFAULT_PROJECT (de .mcp.json o de la variable de entorno del proceso). |
Cómo elige la herramienta. Toma la primera que aplique: input.provider; la forma de la URL
(*.atlassian.net o /browse/ → Jira; dev.azure.com, *.visualstudio.com o /_workitems/ →
Azure DevOps); o paths.user_stories_storage.cloud_provider_mcp si la referencia es una clave o ID
suelto. Si no puede resolverla, si input.provider contradice a la URL, o si la herramienta no está
soportada (hoy, Jira y Azure DevOps), se detiene sin tocar ningún MCP: nunca adivina.
Qué cambia según la herramienta
- MCP:
jira(mcp-atlassian, que arranca conuvx). Antes de empezar verifica queuvesté instalado y, si falta, intenta instalarlo según tu sistema operativo. - Identificador: la clave del issue (
TS-42), también extraída de URLs/browse/…o de un board (?selectedIssue=TS-42). - Texto: el server ya devuelve la descripción en markdown; se preserva tal cual.
- Criterios de aceptación: el custom field
jira.acceptance_criteria_fielddeqa-stack.yamlsi está configurado; si no, los busca en la descripción y, por último, en las páginas de Confluence traídas. - Confluence: si el issue enlaza páginas de Confluence (hasta 5), las trae también y enriquece
el contenido con esa spec (objetivo, contexto, info técnica), atribuyendo cada sección a su
fuente. Es opcional y nunca frena la skill: si falla, sigue con el issue y lo avisa en
warnings. Conjira.follow_confluence_links: falseno sigue esos links. - Configuración:
JIRA_URLse resuelve desde.mcp.jsony, si no está, desde la variable de entorno del proceso.
- MCP:
azure-devops(@tiberriver256/mcp-server-azure-devops, que arranca connpx). Antes de empezar verifica quenode/npxestén instalados y, si faltan, indica cómo instalar Node.js. - Identificador: el ID entero del work item (
1234), también extraído de URLs…/_workitems/edit/1234. - Texto: Azure DevOps devuelve los campos de texto en HTML; la skill los convierte a markdown
de forma fiel. En un Bug sin descripción, usa los pasos de reproducción (
ReproSteps). - Criterios de aceptación: el campo
azure_devops.acceptance_criteria_fielddeqa-stack.yaml(defaultMicrosoft.VSTS.Common.AcceptanceCriteria); si está ennullo vacío, los busca en la descripción. Nunca vienen de Confluence. - Sin contenido enlazado: hace una traducción fiel estricta — no reordena, no reestructura ni agrega secciones que el work item no tiene.
- Configuración:
AZURE_DEVOPS_ORG_URLy el proyecto por defecto se resuelven desde.mcp.jsony, si no están, desde la variable de entorno del proceso.
Solo lectura, en memoria y con los datos sensibles enmascarados
Nunca modifica el ticket (no comenta, no transiciona, no edita) y nunca escribe en disco: el
contenido se devuelve solo en memoria y cada invocación trae el estado fresco del ticket. Antes de
armar el contenido enmascara con ******** las contraseñas, tokens, cookies, cadenas de conexión
y datos personales que encuentre en los textos copiados del ticket, y lo avisa en warnings (con
el campo y el ID del ticket, sin repetir el valor). Si JIRA_URL, AZURE_DEVOPS_ORG_URL o el
proyecto no se resuelven ni en .mcp.json ni en el entorno, se detiene antes de llamar al MCP.
Salida
| Campo | Descripción |
|---|---|
provider |
jira | azure-devops: herramienta de la que se trajo el ticket. |
story_id |
Clave (TS-42) o ID (1234) del ticket, para trazabilidad. |
content |
Contenido completo en formato canónico, en memoria, listo para lippia-neo-read-user-story. |
source_url |
URL canónica del ticket. |
title / story_type / status |
Título, tipo (Story/Bug/Task/… en Jira; User Story/Bug/Task/Feature en Azure DevOps) y estado del ticket. |
ac_source |
De dónde salieron los criterios de aceptación (custom_field | description | confluence | none; confluence solo con Jira). |
confluence_pages |
Solo con Jira: páginas de Confluence traídas (page_id, title, url). |
summary |
Resumen legible de la operación. |
warnings |
Advertencias (ej. descripción vacía, Confluence MCP no disponible, campos enmascarados). |
Se encadena con
Se ejecuta antes de lippia-neo-read-user-story (paso 1 de lippia-neo-meta-run-user-story-e2e). Nunca escribe
ni toca el directorio local de historias. En un plan se declara un paso por herramienta, con
provider fijo y la tool file además de la del MCP (jira o azure-devops), para que la skill
pueda leer su archivo de referencia.
lippia-neo-read-bug-report
Cuándo usarla
Al iniciar trabajo de QA sobre un bug reportado (no una historia de usuario). Acepta, a través
de un único campo, tres formas detectadas automáticamente por su contenido: path local a un
.md, URL de ticket (Jira/Azure DevOps), o texto crudo ya disponible (por ejemplo, inyectado
por el dispatcher M2). Extrae pasos de reproducción, resultado esperado vs. obtenido,
severidad, entorno y cualquier criterio de aceptación/historia referenciada.
{
"input": {
"bug_report": "El botón 'Aplicar cupón' no muestra el descuento al confirmar un cupón válido en el carrito."
}
}
| Input | Tipo | Descripción |
|---|---|---|
input.bug_report |
Requerido | Path local, URL de ticket remoto, o texto crudo del bug; la forma se detecta automáticamente por el contenido. No hay una clave propia para bugs en qa-stack.yaml: un path relativo se busca también bajo paths.user_stories_storage.local_path; si guardás los bugs en otra carpeta, pasá el path completo. |
input.identifier |
Opcional | Identificador ya resuelto por quien la invoca; tiene prioridad sobre el bug_id derivado del ticket. |
input.credentials |
Opcional | Credenciales de prueba ya resueltas por quien la invoca; tienen prioridad sobre lo que la skill encuentre mencionado en el reporte. |
Salida
| Campo | Descripción |
|---|---|
bug_id / identifier |
Identificador corto del bug, y su alias normalizado. |
title |
Título del bug. |
steps_to_reproduce / expected_result / actual_result |
Texto literal del reporte, nunca inventado. |
severity |
Tal como esté clasificada; vacía si no está. |
environment |
URL/browser/versión mencionados. |
related_user_story |
Referencia a la historia/feature relacionada, o null (no se resuelve acá). |
app_urls / credentials |
URL(s) de la app y credenciales de prueba referenciadas. |
source_kind |
local_path | jira | azure-devops | raw_text. |
bug_report_path / source_url |
Ruta local o URL del ticket, según source_kind. |
can_continue |
true si hubo contenido suficiente para caracterizar el bug; null si no (nunca false). |
Se encadena con
Punto de entrada de bugs, análogo a lippia-neo-read-user-story. Para URLs despacha a
lippia-neo-fetch-user-story. Sigue con lippia-neo-find-existing-tests →
lippia-neo-reproduce-bug → lippia-neo-generate-test-suite → ....
lippia-neo-resolve-user-story-source
Cuándo usarla
Cuando un plan u orquestador (M2/M4) necesita decidir dónde leer una referencia de historia
de usuario — path local o ticket remoto — antes de decidir si ejecuta una skill de fetch. Es una
decisión de ruteo pura: solo clasifica y valida una URL contra la configuración del proyecto;
nunca lee un archivo, nunca toca Jira/Azure, nunca fetchea nada. Si la URL no corresponde al
proveedor (paths.user_stories_storage.cloud_provider_mcp) ni a la instancia configurada en
.mcp.json, se detiene con el motivo en vez de clasificarla.
{
"input": {
"user_story": "https://tu-sitio.atlassian.net/browse/TS-42"
}
}
| Input | Tipo | Descripción |
|---|---|---|
input.user_story |
Requerido | Path local a un .md o URL de un ticket remoto. |
input.user_story_ref |
Opcional | Alias explícito de la referencia, si no se usa input.user_story. |
Salida
| Campo | Descripción |
|---|---|
kind |
local_path | jira | azure-devops: a dónde hay que ir a buscar el contenido. |
fetch_url_jira |
La URL tal cual, solo si kind == jira (se pasa a input.story_ref de lippia-neo-fetch-user-story, con provider: jira); null en otro caso. |
fetch_url_azure_devops |
La URL tal cual, solo si kind == azure-devops (se pasa a input.story_ref de lippia-neo-fetch-user-story, con provider: azure-devops); null en otro caso. |
reason |
Una línea explicando la clasificación (para logs/debug). |
Se encadena con
Primer eslabón de la cadena de resolución de historias en planes M4; según kind, dispara
lippia-neo-fetch-user-story (con provider: jira o provider: azure-devops), y siempre continúa con
lippia-neo-read-user-story → lippia-neo-create-test-plan → ....
lippia-neo-read-test-plan
Cuándo usarla
Cuando una skill o un plan necesita la información de un plan de pruebas en Markdown ya
estructurada como datos, en vez de parsear el .md por su cuenta. Lee el plan desde su path
local (típicamente test-plans/<US-ID>-test-plan.md, generado por
lippia-neo-create-test-plan) y extrae todo:
encabezado, alcance, cobertura de criterios de aceptación, datos de prueba, precondiciones,
escenarios completos con sus pasos y preguntas abiertas. Es de solo lectura y literal: no
persiste nada, no corrige ni completa escenarios, y no se conecta a herramientas externas —
si le pasás una URL, falla.
{
"input": {
"test_plan_path": "test-plans/LTM-21-test-plan.md"
}
}
| Input | Tipo | Descripción |
|---|---|---|
input.test_plan_path |
Requerido | Path (absoluto o relativo) al plan en Markdown; si no lo encuentra tal cual, lo busca relativo a la raíz del repo y a paths.test_plans_dir de qa-stack.yaml (default test-plans/). Solo paths locales. |
Salida
| Campo | Descripción |
|---|---|
status |
read si se leyó el plan con al menos un escenario; failed si no hubo referencia, era una URL, el archivo no existe/está vacío o no tiene escenarios (el motivo va como primer warning). |
test_plan_path |
Ruta efectivamente leída. |
us_id / identifier |
Identificador de la historia, tomado del nombre del archivo o del H1 del plan, y su alias normalizado. |
header |
Encabezado del plan: título, historia, URL de la app, credenciales, stack, fuente de los escenarios y otras etiquetas (extra). |
scope |
Alcance incluido / fuera de alcance, o null si el plan no lo trae. |
acceptance_criteria_coverage |
Matriz de cobertura: por cada criterio (id, title), los escenarios que lo cubren. |
test_data / general_preconditions |
Datos de prueba generales y precondiciones generales. test_data trae las tablas y notas tal cual y, además, los datos tipados: reference_data, variables y partitions (la misma forma que devuelve lippia-neo-create-test-plan). |
scenarios |
Escenarios completos: id, title, acceptance_criteria, type, priority, preconditions, steps (acción + resultado esperado por paso), test_data, y los campos tipados scope, state, state_reason y data_records (ver abajo). |
open_questions |
Preguntas abiertas y riesgos del plan. |
other_sections / missing_sections |
Secciones que no mapean a ningún campo (nunca se pierden) y secciones esperadas que el plan no tiene. |
warnings |
Inconsistencias detectadas (matriz vs. escenarios, pasos sin resultado esperado, posibles credenciales literales, etc.); se señalan, nunca se corrigen. |
Contrato tipado del plan
lippia-neo-read-test-plan devuelve los mismos campos tipados que
lippia-neo-create-test-plan, para que cualquier skill
consuma un plan igual, lo haya escrito NEO o una persona. Los campos salen solo del formato del
plan, nunca de lo que el texto "quiere decir". Dos diferencias:
scopepuede sernullsi el plan no declara**Alcance:**.- Un dato con una forma que no reconoce queda con
source: unknowny un aviso; las skills que lo consumen no lo interpretan.
El state se resuelve en este orden: **Estado:** sin resultado esperado → un paso con
⚠️ sin resultado esperado → **Estado:** bloqueado → un paso sin resultado esperado → ready.
El resumen de consola informa cuántos escenarios hay listos · bloqueados · por confirmar · sugeridos.
Así lo usan las demás skills:
| Skill | Qué toma en cuenta |
|---|---|
lippia-neo-generate-test-suite |
blocked → caso bloqueado; needs_confirmation → no se genera; suggested → @sugerido. Los datos de cada caso salen de data_records (ver Data-driven testing) |
lippia-neo-run-manual-testing |
Ejecuta solo los escenarios ready (los demás quedan blocked, sin pasos); los datos de partición se prueban uno por uno |
lippia-neo-meta-normalize-test-cases |
Copia scope, state, state_reason y data_records a cada test case, sin filtrar |
lippia-neo-meta-export-test-cases |
Exporta solo los ready que no son sugeridos (no es configurable); el resto queda en normalization.excluded con su motivo |
lippia-neo-run-and-heal |
No intenta reparar los escenarios bloqueados |
lippia-neo-generate-test-data |
Solo genera datos para escenarios ready; nunca completa datos pending ni reference |
lippia-neo-meta-run-user-story-e2e |
Un criterio de aceptación cuyos escenarios están todos bloqueados o sin resultado esperado no frena el flujo: se informa como pendiente |
Se encadena con
Se ejecuta después de lippia-neo-create-test-plan, sobre el plan que esa skill dejó en disco. Hoy la
consume lippia-neo-meta-normalize-test-cases (y, a través de ella, lippia-neo-meta-export-test-cases).
Quien la consuma debe chequear status antes de usar el resultado.