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).
{
"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.
{
"input": {
"story_ref": "https://your-site.atlassian.net/browse/TS-42"
}
}
{
"input": {
"story_ref": "https://dev.azure.com/your-org/your-project/_workitems/edit/1234"
}
}
{
"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 withuvx). Before starting it checks thatuvis 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_fieldfromqa-stack.yamlif 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. Withjira.follow_confluence_links: falseit doesn't follow those links. - Configuration:
JIRA_URLis resolved from.mcp.jsonand, if it isn't there, from the process environment variable.
- MCP:
azure-devops(@tiberriver256/mcp-server-azure-devops, which starts withnpx). Before starting it checks thatnode/npxare 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/1234URLs. - 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_fieldfield fromqa-stack.yaml(defaultMicrosoft.VSTS.Common.AcceptanceCriteria); if it'snullor 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_URLand the default project are resolved from.mcp.jsonand, 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.
{
"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.
{
"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.
{
"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:
scopecan benullif the plan doesn't declare**Alcance:**.- A data item with a shape it doesn't recognize is left with
source: unknownand 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.