Saltar a contenido

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).

Ejemplo de invocación
{
  "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.

Ejemplo de invocación (Jira)
{
  "input": {
    "story_ref": "https://tu-sitio.atlassian.net/browse/TS-42"
  }
}
Ejemplo de invocación (Azure DevOps)
{
  "input": {
    "story_ref": "https://dev.azure.com/tu-org/tu-proyecto/_workitems/edit/1234"
  }
}
Ejemplo con un ID suelto
{
  "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 con uvx). Antes de empezar verifica que uv esté 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_field de qa-stack.yaml si 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. Con jira.follow_confluence_links: false no sigue esos links.
  • Configuración: JIRA_URL se resuelve desde .mcp.json y, si no está, desde la variable de entorno del proceso.
  • MCP: azure-devops (@tiberriver256/mcp-server-azure-devops, que arranca con npx). Antes de empezar verifica que node / npx esté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_field de qa-stack.yaml (default Microsoft.VSTS.Common.AcceptanceCriteria); si está en null o 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_URL y el proyecto por defecto se resuelven desde .mcp.json y, 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.

Ejemplo de invocación
{
  "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.

Ejemplo de invocación
{
  "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.

Ejemplo de invocación
{
  "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:

  • scope puede ser null si el plan no declara **Alcance:**.
  • Un dato con una forma que no reconoce queda con source: unknown y 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.