Skip to content

Reading and ingestion of stories and bugs

These five skills are the entry point of almost any QA flow: they normalize a user story or a reported bug — whether it comes from a local file, from Jira, or from Azure DevOps — into a common data structure that the rest of the skills can consume without wondering where it came from. The fifth one, lippia-neo-read-test-plan, does the same with a test plan already written to disk.

None of them writes to disk when the source is remote

Content fetched from Jira/Azure DevOps is always kept in memory; it's never persisted to the local stories directory.


lippia-neo-read-user-story

When to use it

When starting a QA flow on a user story. It receives a reference — a local path to a .md file or the URL of a ticket (Jira / Azure DevOps) — resolves it automatically, and extracts the summary, the acceptance criteria, the app URL, the test credentials, and the key features to test. It's the standard entry point of any story-based flow (the counterpart of lippia-neo-read-bug-report for bugs).

Invocation example
{
  "input": {
    "user_story": "user-stories/PA-US-02.md"
  }
}
Input Type Description
input.user_story Required Local path to a .md file or URL of a remote ticket; it's never hardcoded. A path is always read from disk (also trying it relative to paths.user_stories_storage.local_path); a URL is only processed if its provider matches paths.user_stories_storage.cloud_provider_mcp in qa-stack.yaml and its host matches the instance configured in .mcp.json — otherwise, the skill stops.
input.user_story_ref Optional Explicit alias of the reference, if input.user_story isn't used.
input.identifier Optional Identifier already resolved by the caller; it takes priority over the us_id derived from the story.
input.jira_content / input.jira_source_url Optional Content already fetched by lippia-neo-fetch-user-story with provider: jira (typical of an M2/M4 plan that has already resolved the source); if present, it takes priority over input.user_story.
input.azure_content / input.azure_source_url Optional Same criterion, for content already fetched by lippia-neo-fetch-user-story with provider: azure-devops.

Output

Field Description
us_id / identifier Short identifier of the story, and its normalized alias.
summary Summary of the story.
acceptance_criteria List of acceptance criteria.
app_urls URL(s) of the app under test.
credentials Referenced test credentials.
key_features Key features to test.
source_kind local_path | jira | azure-devops.
user_story_path / source_url Local path or URL of the source ticket, depending on source_kind.
can_continue true if there was enough context to summarize with confidence; null if not (never false).
Chains with

First step of any story-based flow (lippia-neo-meta-run-user-story-e2e, M2/M4 plans). For remote URLs, it dispatches to lippia-neo-fetch-user-story (Jira or Azure DevOps, depending on the source). It continues with 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 of lippia-neo-read-user-story

You don't need to invoke it directly: you invoke lippia-neo-read-user-story and this subskill is chosen automatically when you pass it the URL or key/ID of a Jira or Azure DevOps ticket.

When to use it

When QA work needs to start from a ticket in the management tool — a Jira Cloud issue or an Azure DevOps work item — instead of a local .md file. It fetches the ticket via the tool's MCP (jira or azure-devops) and returns it structured in memory, ready for lippia-neo-read-user-story (or lippia-neo-meta-run-user-story-e2e) to consume directly. It accepts a bare key or ID (TS-42, 1234), the ticket URL, or the slash command argument: /lippia-neo-fetch-user-story <key-ID-or-URL>.

It's a single skill for both tools: the common procedure (resolving the tool, mapping fields, masking sensitive data, building the canonical content) lives in its SKILL.md, and what's specific to each tool — which MCP to use, how to read the identifier, where the acceptance criteria come from — lives in a reference file (references/jira.md, references/azure-devops.md) that it reads before the first MCP call.

Invocation example (Jira)
{
  "input": {
    "story_ref": "https://your-site.atlassian.net/browse/TS-42"
  }
}
Invocation example (Azure DevOps)
{
  "input": {
    "story_ref": "https://dev.azure.com/your-org/your-project/_workitems/edit/1234"
  }
}
Example with a bare ID
{
  "input": {
    "story_ref": "1234",
    "provider": "azure-devops"
  }
}
Input Type Description
input.story_ref Required Key, ID, or URL of the ticket (TS-42, 1234, or the Jira / Azure DevOps URL); the skill extracts the canonical identifier.
input.provider Optional jira | azure-devops. If not provided, the tool is detected from the shape of the URL; with a bare key or ID, it's taken from paths.user_stories_storage.cloud_provider_mcp in qa-stack.yaml.
input.project Optional Azure DevOps only: Team Project override; if not provided, it uses azure_devops.default_project from qa-stack.yaml and, failing that, AZURE_DEVOPS_DEFAULT_PROJECT (from .mcp.json or the process environment variable).

How it picks the tool. It takes the first one that applies: input.provider; the shape of the URL (*.atlassian.net or /browse/ → Jira; dev.azure.com, *.visualstudio.com, or /_workitems/ → Azure DevOps); or paths.user_stories_storage.cloud_provider_mcp if the reference is a bare key or ID. If it can't resolve it, if input.provider contradicts the URL, or if the tool isn't supported (today, Jira and Azure DevOps), it stops without touching any MCP: it never guesses.

What changes depending on the tool

  • MCP: jira (mcp-atlassian, which starts with uvx). Before starting it checks that uv is installed and, if it's missing, tries to install it based on your operating system.
  • Identifier: the issue key (TS-42), also extracted from /browse/… URLs or from a board (?selectedIssue=TS-42).
  • Text: the server already returns the description as markdown; it's preserved as is.
  • Acceptance criteria: the custom field jira.acceptance_criteria_field from qa-stack.yaml if it's configured; if not, it looks for them in the description and, lastly, in the Confluence pages it fetched.
  • Confluence: if the issue links to Confluence pages (up to 5), it fetches them too and enriches the content with that spec (goal, context, technical info), attributing each section to its source. It's optional and never stops the skill: if it fails, it continues with the issue and flags it in warnings. With jira.follow_confluence_links: false it doesn't follow those links.
  • Configuration: JIRA_URL is resolved from .mcp.json and, if it isn't there, from the process environment variable.
  • MCP: azure-devops (@tiberriver256/mcp-server-azure-devops, which starts with npx). Before starting it checks that node / npx are installed and, if they're missing, tells you how to install Node.js.
  • Identifier: the integer ID of the work item (1234), also extracted from …/_workitems/edit/1234 URLs.
  • Text: Azure DevOps returns the text fields as HTML; the skill converts them to markdown faithfully. For a Bug with no description, it uses the reproduction steps (ReproSteps).
  • Acceptance criteria: the azure_devops.acceptance_criteria_field field from qa-stack.yaml (default Microsoft.VSTS.Common.AcceptanceCriteria); if it's null or empty, it looks for them in the description. They never come from Confluence.
  • No linked content: it does a strict faithful translation — it doesn't reorder, restructure, or add sections the work item doesn't have.
  • Configuration: AZURE_DEVOPS_ORG_URL and the default project are resolved from .mcp.json and, if they aren't there, from the process environment variable.

Read-only, in memory, and with sensitive data masked

It never modifies the ticket (it doesn't comment, transition, or edit) and never writes to disk: the content is only returned in memory, and each invocation fetches the ticket's fresh state. Before building the content, it masks with ******** the passwords, tokens, cookies, connection strings, and personal data it finds in the text copied from the ticket, and flags it in warnings (with the field and the ticket ID, without repeating the value). If JIRA_URL, AZURE_DEVOPS_ORG_URL, or the project can't be resolved from either .mcp.json or the environment, it stops before calling the MCP.

Output

Field Description
provider jira | azure-devops: the tool the ticket was fetched from.
story_id Key (TS-42) or ID (1234) of the ticket, for traceability.
content Full content in canonical format, in memory, ready for lippia-neo-read-user-story.
source_url Canonical URL of the ticket.
title / story_type / status Title, type (Story/Bug/Task/… in Jira; User Story/Bug/Task/Feature in Azure DevOps), and status of the ticket.
ac_source Where the acceptance criteria came from (custom_field | description | confluence | none; confluence only with Jira).
confluence_pages Jira only: fetched Confluence pages (page_id, title, url).
summary Readable summary of the operation.
warnings Warnings (e.g. empty description, Confluence MCP not available, masked fields).
Chains with

Runs before lippia-neo-read-user-story (step 1 of lippia-neo-meta-run-user-story-e2e). It never writes to or touches the local stories directory. In a plan, you declare one step per tool, with a fixed provider and the file tool in addition to the MCP's (jira or azure-devops), so that the skill can read its reference file.


lippia-neo-read-bug-report

When to use it

When starting QA work on a reported bug (not a user story). Through a single field, it accepts three forms, detected automatically from their content: a local path to a .md file, a ticket URL (Jira/Azure DevOps), or raw text already available (for example, injected by the M2 dispatcher). It extracts reproduction steps, expected vs. actual result, severity, environment, and any referenced acceptance criterion/story.

Invocation example
{
  "input": {
    "bug_report": "The 'Apply coupon' button does not show the discount when a valid coupon is confirmed in the cart."
  }
}
Input Type Description
input.bug_report Required Local path, remote ticket URL, or raw text of the bug; the form is detected automatically from the content. There's no dedicated key for bugs in qa-stack.yaml: a relative path is also searched under paths.user_stories_storage.local_path; if you store bugs in another folder, pass the full path.
input.identifier Optional Identifier already resolved by the caller; it takes priority over the bug_id derived from the ticket.
input.credentials Optional Test credentials already resolved by the caller; they take priority over whatever the skill finds mentioned in the report.

Output

Field Description
bug_id / identifier Short identifier of the bug, and its normalized alias.
title Title of the bug.
steps_to_reproduce / expected_result / actual_result Literal text from the report, never made up.
severity As classified; empty if it isn't.
environment URL/browser/version mentioned.
related_user_story Reference to the related story/feature, or null (it isn't resolved here).
app_urls / credentials URL(s) of the app and referenced test credentials.
source_kind local_path | jira | azure-devops | raw_text.
bug_report_path / source_url Local path or URL of the ticket, depending on source_kind.
can_continue true if there was enough content to characterize the bug; null if not (never false).
Chains with

Entry point for bugs, the counterpart of lippia-neo-read-user-story. For URLs it dispatches to lippia-neo-fetch-user-story. It continues with lippia-neo-find-existing-tests → lippia-neo-reproduce-bug → lippia-neo-generate-test-suite → ....


lippia-neo-resolve-user-story-source

When to use it

When a plan or orchestrator (M2/M4) needs to decide where to read a user story reference from — local path or remote ticket — before deciding whether to run a fetch skill. It's a pure routing decision: it only classifies and validates a URL against the project's configuration; it never reads a file, never touches Jira/Azure, never fetches anything. If the URL doesn't match the provider (paths.user_stories_storage.cloud_provider_mcp) or the instance configured in .mcp.json, it stops with the reason instead of classifying it.

Invocation example
{
  "input": {
    "user_story": "https://your-site.atlassian.net/browse/TS-42"
  }
}
Input Type Description
input.user_story Required Local path to a .md file or URL of a remote ticket.
input.user_story_ref Optional Explicit alias of the reference, if input.user_story isn't used.

Output

Field Description
kind local_path | jira | azure-devops: where the content needs to be fetched from.
fetch_url_jira The URL as-is, only if kind == jira (it's passed to input.story_ref of lippia-neo-fetch-user-story, with provider: jira); null otherwise.
fetch_url_azure_devops The URL as-is, only if kind == azure-devops (it's passed to input.story_ref of lippia-neo-fetch-user-story, with provider: azure-devops); null otherwise.
reason One line explaining the classification (for logs/debugging).
Chains with

First link in the story resolution chain in M4 plans; depending on kind, it triggers lippia-neo-fetch-user-story (with provider: jira or provider: azure-devops), and it always continues with lippia-neo-read-user-story → lippia-neo-create-test-plan → ....


lippia-neo-read-test-plan

When to use it

When a skill or a plan needs the information of a Markdown test plan already structured as data, instead of parsing the .md file on its own. It reads the plan from its local path (typically test-plans/<US-ID>-test-plan.md, generated by lippia-neo-create-test-plan) and extracts everything: header, scope, acceptance criteria coverage, test data, preconditions, full scenarios with their steps, and open questions. It's read-only and literal: it doesn't persist anything, doesn't correct or complete scenarios, and doesn't connect to external tools — if you pass it a URL, it fails.

Invocation example
{
  "input": {
    "test_plan_path": "test-plans/LTM-21-test-plan.md"
  }
}
Input Type Description
input.test_plan_path Required Path (absolute or relative) to the Markdown plan; if it can't find it as given, it looks for it relative to the repo root and to paths.test_plans_dir in qa-stack.yaml (default test-plans/). Local paths only.

Output

Field Description
status read if the plan was read with at least one scenario; failed if there was no reference, it was a URL, the file doesn't exist/is empty, or it has no scenarios (the reason goes as the first warning).
test_plan_path Path actually read.
us_id / identifier Story identifier, taken from the file name or the plan's H1, and its normalized alias.
header Plan header: title, story, app URL, credentials, stack, source of the scenarios, and other labels (extra).
scope In scope / out of scope, or null if the plan doesn't include it.
acceptance_criteria_coverage Coverage matrix: for each criterion (id, title), the scenarios that cover it.
test_data / general_preconditions General test data and general preconditions. test_data includes the tables and notes as is and, in addition, the typed data: reference_data, variables, and partitions (the same shape returned by lippia-neo-create-test-plan).
scenarios Full scenarios: id, title, acceptance_criteria, type, priority, preconditions, steps (action + expected result per step), test_data, and the typed fields scope, state, state_reason, and data_records (see below).
open_questions Open questions and risks of the plan.
other_sections / missing_sections Sections that don't map to any field (they're never lost) and expected sections that the plan doesn't have.
warnings Detected inconsistencies (matrix vs. scenarios, steps without an expected result, possible literal credentials, etc.); they're flagged, never corrected.

Typed plan contract

lippia-neo-read-test-plan returns the same typed fields as lippia-neo-create-test-plan, so that any skill consumes a plan the same way, whether it was written by NEO or by a person. The fields come only from the format of the plan, never from what the text "means". Two differences:

  • scope can be null if the plan doesn't declare **Alcance:**.
  • A data item with a shape it doesn't recognize is left with source: unknown and a warning; the skills that consume it don't interpret it.

The state is resolved in this order: **Estado:** sin resultado esperado → a step with ⚠️ sin resultado esperado → **Estado:** bloqueado → a step without an expected result → ready. The console summary reports how many scenarios are ready · blocked · pending confirmation · suggested.

This is how the other skills use it:

Skill What it takes into account
lippia-neo-generate-test-suite blocked → blocked case; needs_confirmation → not generated; suggested → @sugerido. Each case's data comes from data_records (see Data-driven testing)
lippia-neo-run-manual-testing Runs only the ready scenarios (the rest are left blocked, with no steps); partition data is tested one by one
lippia-neo-meta-normalize-test-cases Copies scope, state, state_reason, and data_records to each test case, without filtering
lippia-neo-meta-export-test-cases Exports only the ready ones that aren't suggested (not configurable); the rest are left in normalization.excluded with their reason
lippia-neo-run-and-heal Doesn't try to repair blocked scenarios
lippia-neo-generate-test-data Only generates data for ready scenarios; it never fills in pending or reference data
lippia-neo-meta-run-user-story-e2e An acceptance criterion whose scenarios are all blocked or without an expected result doesn't stop the flow: it's reported as pending
Chains with

Runs after lippia-neo-create-test-plan, on the plan that skill left on disk. Currently it's consumed by lippia-neo-meta-normalize-test-cases (and, through it, lippia-neo-meta-export-test-cases). Whoever consumes it must check status before using the result.