sprint-testing

Forbidden invocations

NEVER invoke /sdd-* skills from this workflow. SDD is an optional user-installed ceremony; this skill ships self-contained and does not chain SDD under any condition. If you need to refactor KATA, fixtures, cli/, scripts/, or api/schemas/ pipeline, exit this skill first and invoke /framework-development — which itself runs Plan → Code → Verify → Archive natively (no SDD required).

This boundary is mechanical, not advisory: scripts/lint-skills.ts rejects any /sdd- mention outside this section. See: .agents/skills/agentic-qa-core/references/skill-composition-strategy.md §4 (governs users who manually install SDD).

Sprint Testing — Plan, Execute, Report per Ticket

Drive the manual / exploratory QA loop for a single ticket during a sprint. Three stages, always in this order: Stage 1 Planning -> Stage 2 Execution -> Stage 3 Reporting. Hand off afterwards to the skills that own Stage 4, 5 and 6.

The same three-stage pipeline runs in every mode. Only the entry point and the bookkeeping differ: one issue at a time (single-issue), or the whole sprint's QA backlog driven by a sprint-level session pair (sprint-wide).

"Issue", not "story", throughout: Story, Bug, Defect, Improvement, Tech Story and Tech Debt are all coverable, and the sprint queue holds whichever of them the project declares.

Dependencies

Requires agentic-qa-core. Loads on demand:

agentic-qa-core/references/test-design-doctrine.md — MANDATORY before designing any ATP / TC coverage from acceptance criteria. Governs the 5 principles, the floor-not-ceiling coverage model, the 1:N explode-default rule, and the formal-technique triggers.
agentic-qa-core/references/defect-management-doctrine.md — MANDATORY before taking a Story into testing and before filing any Bug / Defect / Improvement. Governs issue-type classification (Bug vs Defect vs Improvement by feature lifecycle), the QA-Assignee self-assign + never-overwrite rule, mandatory Components, the three-axis model (parent = QA process epic · link = source Story · components = product module), and Severity→Priority auto-derive.
agentic-qa-core/references/briefing-template.md, agentic-qa-core/references/dispatch-patterns.md, agentic-qa-core/references/orchestration-doctrine.md, agentic-qa-core/references/session-management.md, agentic-qa-core/references/preflight-gate.md, agentic-qa-core/references/adr-doctrine.md — cited inline by the sections that use them.

Compact Rules

Test-design doctrine (binding — full canon: agentic-qa-core/references/test-design-doctrine.md):

AC-pass is the FLOOR, not the goal. Coverage = AC-conformance + risk-beyond-AC (boundaries, errors, states, anomalies). Never report "% of ACs verified" as completeness.
1:N is the default: explode every non-trivial AC into multiple cases (EP partitions + boundaries + states + contexts). Collapsing an AC to one case requires a written "trivially atomic" justification.
Apply techniques by trigger: EP always; BVA wherever a range / limit / length / date-window exists; State-Transition for stateful entities; Decision Table when 2+ conditions interact; Pairwise when 3+ combinable factors (log the reduction); Error-Guessing charters for experience-based risk.
A criterion is a business assertion; a test case is a concrete exploration of it. Run the Test-Design Checklist before finalizing the ATP.

Defect-management doctrine (binding — full canon: agentic-qa-core/references/defect-management-doctrine.md):

CLASSIFY before filing — stop hardcoding "Bug". Bug = affected feature already live above Staging (end-user visible); Defect = feature still pre-release (Staging or below), the normal output of sprint testing; Improvement = not a broken AC (an enhancement, or an under-specified/absent AC surfaced by a test-beyond-AC). Classification follows the FEATURE's lifecycle stage, not where the problem was found (Part 1).
qa_assignee ({{jira.qa_assignee}}) = the authenticated session user (self-assign). Set it when a Story is TAKEN INTO TESTING (start_testing) and on every filed Bug / Defect / Improvement. NEVER-OVERWRITE an existing owner (read-before-write); distinct from the native dev assignee (Part 2).
components (native, MANDATORY) = the affected product module/Epic, must pre-exist in the Jira Components module (Part 3).
Three-axis model: parent = QA Defect Management process epic (qa.qa_epics.defect_epic, found-or-created — NEVER a product/dev epic, NEVER the Story); issue link = the source Story (traceability); components = product module (Part 4).
priority (native) is auto-derived from {{jira.severity}} (critica→Highest, mayor→High, moderada→Medium, menor→Low, trivial→Lowest); override with a 1-line justification (Part 5.1).

Sprint-testing operational rules:

Three stages, always in order: Stage 1 Planning → Stage 2 Execution → Stage 3 Reporting. Hand off Stages 4/5/6 to test-documentation / test-automation / regression-testing.
Jira is source of truth. Read tickets via bun run jira:sync-issues get <KEY> --include-comments, then the synced .md. NEVER acli workitem view for custom fields (returns null).
Bugs run the veto + triage + risk-score decision tree BEFORE any ATP is written.
Execution = smoke pass first, then trifuerza (UI/API/DB) exploration; capture evidence under the PBI folder.
API testing = three-tool maneuver: OpenAPI MCP for schema (READ-ONLY) → bun run api:login for the token (→ .auth/tokens.env) → curl for authenticated requests. NEVER execute via the OpenAPI MCP. Canon: agentic-qa-core/references/api-testing-doctrine.md.
Consult domain-glossary.md (if present) before authoring the ATP, refined ACs, and TC outlines.
On any subagent failure: STOP, report partial state, offer retry / skip-stage / abort. No auto-fix, no auto-rollback.
Two modes, ASKED at Session Start, never inferred: sprint-wide (the whole sprint's QA backlog) or single-issue (one issue from it). Only sprint-wide creates the sprint session pair .session/sprint-testing/sprint-<N>/{plan.md, progress.md} and the STP; single-issue creates neither.
The sprint scope is a JQL query built from the work types declared coverable: true in .agents/jira-required.yaml, intersected with what .agents/jira-workflows.json says the instance actually has. Never a hardcoded issue-type list.

Read full SKILL.md when: starting a sprint cold, resuming a session, or handling a bug-triage / sprint-wide flow not covered by the rules above.

Inputs — read these first, in this order

Canonical reading order for any AI starting cold on a sprint-testing workflow. Read in order; stop earlier when the ticket is small enough that later inputs add no signal.

.agents/project.yaml — project identity, env URLs, {{PROJECT_KEY}}, MCP names, active environment.
.agents/jira-required.yaml — canonical slug catalog (custom fields, statuses, transitions) for the active workspace.
.agents/jira-fields.json — slug → numeric custom-field-ID mapping for {{jira.<slug>}} resolution at runtime.
.agents/jira-workflows.json — workflow + transition catalog, the authoritative source of every status / transition name (resolves Ready For QA → In Test → QA Approved for Story / Bug / Test Case work types). A status that is not in this file does not exist in the instance.
.context/PBI/epics/EPIC-<KEY>-<slug>/stories/STORY-<KEY>-<slug>/context.md — ticket-local context: session notes, open questions (hand-authored; read if it already exists from a prior Session Start). NON-Jira file — never a Jira mirror.
.context/master-test-plan.md — regression Epic pointer, modality decision (Xray vs Jira-native), what to test and why.
.context/business/business-feature-map.md — feature catalog vocabulary; resolves "what epic owns this story" for the epics/EPIC-<KEY>-<slug>/ PBI folder naming (module = Epic, 1:1).
.context/business/domain-glossary.md (if present) — canonical domain vocabulary; consult BEFORE authoring the ATP, refined ACs, and TC outlines so test names, entity terms, and Gherkin wording use canonical terms and avoid anti-glossary banned terms. If a new or ambiguous term surfaces during testing, flag it in the Stage 3 QA comment for the PM to add via the glossary's change protocol — NEVER edit the glossary from a testing session.
The Story or Bug ticket itself — AC, ATP, comments — read via bun run jira:sync-issues get <KEY> --include-comments, then read the synced .md files (story.md, acceptance-criteria.md, acceptance-test-plan.md, comments.md) under the STORY folder. Jira is source-of-truth; the synced .md is a read-only cache. NEVER acli workitem view for custom fields — it returns null.
.env — LOCAL_USER_* / STAGING_USER_* credentials. NEVER hardcode; always read at runtime.
kata-manifest.json — registry of existing KATA Components + ATCs. Check before proposing new ATCs in Stage 3 hand-off so the test-automation phase doesn't duplicate work.

Optional inputs. master-test-plan.md, the business maps, and domain-glossary.md frequently arrive after /project-discovery runs and may be absent — proceed without them and surface a missing_input note in the Stage 1 ATP so a later pass can fill the gap. kata-manifest.json is only load-bearing at the Stage 3 → test-automation hand-off; skip in pure manual-QA invocations.

Subagent Dispatch Strategy

Orchestration & Session contracts: this skill follows agentic-qa-core/references/orchestration-doctrine.md (mandatory subagent dispatch — main thread is command center) AND agentic-qa-core/references/session-management.md (Phase 0 resume check, plan-first persistence at .session/<skill-slug>/<scope>/, archive on completion). Phase 0 (resume check) and Phase 1 (plan write) are NOT optional. The orchestrator also applies the per-stage Definition-of-Done gates in agentic-qa-core/references/stage-gates.md: verify a stage's DoD (planning stages include the Test-Design Checklist) BEFORE recording its progress checkpoint and advancing.

This skill runs at two altitudes, and each is a real session scope per agentic-qa-core/references/session-management.md §3 + §9 (§9 "Nested scopes"):

.session/sprint-testing/
├── <JIRA-KEY>/              # single-issue mode
│   ├── plan.md  progress.md  test-session-memory.md
└── sprint-<N>/              # sprint-wide mode
    ├── plan.md              # the local STP: scope, waves, assignment
    ├── progress.md          # append-only sprint log, one entry per issue close
    └── <JIRA-KEY>/          # per-issue sub-scope, identical to single-issue
        └── plan.md  progress.md  test-session-memory.md

Single-issue mode: <scope> = <JIRA-KEY> (e.g. UPEX-123). Sprint-wide mode: the sprint scope is sprint-<N> and each issue's scope is sprint-<N>/<JIRA-KEY>. Both plan.md files follow the §6 schema and both progress.md files the §7 append-only schema — one file format, two altitudes. What a "phase" means is the only difference: at issue altitude a phase is a stage of this skill, at sprint altitude a phase is one issue in the queue.

test-session-memory.md exists at the ISSUE altitude only and is a SEPARATE concern from plan.md: it carries TMS modality + issue context + stage state shared across the 4 sub-agent dispatches (domain memory). All three coexist per issue — plan.md indexes the session, progress.md decides the next stage, test-session-memory.md holds the cross-stage shared payload.

This skill is compliant with the doctrine in AGENTS.md §"Orchestration Mode (Subagent Strategy)" and the session contract in .agents/skills/agentic-qa-core/references/session-management.md. Every dispatch follows the 7-component briefing format defined in .agents/skills/agentic-qa-core/references/briefing-template.md, and the pattern selected per stage matches the decision guide in .agents/skills/agentic-qa-core/references/dispatch-patterns.md. This skill operates in two modes (single-issue and sprint-wide) and BOTH modes use the same four dispatch points per issue — Session Start -> Stage 1 -> Stage 2 -> Stage 3. The only difference is that sprint-wide loops them once per issue. The full briefings (Goal / Context docs / Project Standards (auto-resolved) / Skills to load / Exact instructions / Report format / Rules) live in references/sprint-orchestration.md §"Sub-agent prompt templates".

Stage	Pattern	Subagent role
Session Start (per-issue)	Single	dispatch a session-start subagent: fetch the issue from the issue tracker, load `.context/`, create the PBI folder + `context.md` and the session dir + `test-session-memory.md`, return issue summary + AC list
Stage 1 — Planning (ATP + draft TCs + risk triage)	Sequential	dispatch a Planning subagent: produce the ATP artifact + risk score + draft TC outlines; bug tickets get the veto + triage decision tree applied
Stage 2 — Execution (smoke + UI/API/DB exploration)	Sequential	dispatch an Execution subagent: smoke pass first, then triforce (UI/API/DB) exploration; capture evidence under the PBI folder; surface BUG_FOUND if applicable
Stage 3 — Reporting (ATR + QA comment + transition)	Sequential	dispatch a Reporting subagent: fill the ATR, post the QA comment, transition the issue, file bug reports if any

Modes are equivalent in dispatch shape. Single-issue mode runs ONE pass through these four dispatches. Sprint-wide loops them per issue. There is no longer a "single-issue inline" path — both modes pay the same 4-dispatch cost so behavior is uniform and reviews are consistent.

Sequential, not Parallel: each stage feeds the next (Session Start's PBI folder is read by Stage 1; Stage 1's ATP is read by Stage 2; Stage 2's evidences are read by Stage 3). Parallelism inside a single issue would race on shared PBI state.

On any subagent failure: STOP, report the partial state (which stages completed, what artifacts landed), present retry / skip-stage / abort options. Do NOT auto-fix nor auto-rollback. See .agents/skills/agentic-qa-core/references/orchestration-doctrine.md.

Scope — ASK for the mode first

Mode	Input	Output	Use when
single-issue — User Story	One story key (e.g. `{{PROJECT_KEY}}-123`)	ATP + ATR + QA comment + issue moved to {{jira.status.story.qa_approved}}. TC artifacts depend on modality: jira-native → outlines only (regression TCs created in Stage 4); jira-xray → created + executed `Test`s this sprint, promoted to regression in Stage 4 (see "TC creation timing")	Full QA on one story end to end
single-issue — Bug	One bug key	Triage decision, then either Code-Review-only OR ATP + ATR + verification report	Retesting a bug fix on staging
sprint-wide	Sprint number `N`	Sprint session pair (`plan.md` queue + append-only `progress.md`) · STP found-or-created and maintained · per-issue artifacts · session summary	Running the whole sprint's QA backlog, with interruption + resume support

The mode question (MANDATORY — asked, never inferred)

Session Start asks this explicitly, in one question, before anything else:

Run the whole sprint's QA backlog (sprint-wide), or one issue from it (single-issue)?

A sprint number in the invocation is a strong hint, not an answer — "QA sprint 12" can mean either. Ask, then apply:

Answer	Sprint session pair	STP	Per-issue sub-scopes
`sprint-wide`	created at `.session/sprint-testing/sprint-<N>/`	found-or-created and kept current	`sprint-<N>/<JIRA-KEY>/`, one per issue
`single-issue`	not created	not created (exactly as today)	`<JIRA-KEY>/` at the top level

Sprint scope is a JQL query, never a hardcoded type list

The sprint's QA backlog is resolved by QUERY. NEVER write a literal issue-type list as the rule — a project whose Jira has only Story must work, and so must one that added Tech Debt. Resolve it in four steps:

Read .agents/jira-required.yaml and take every work type declared coverable: true.
For each, resolve jira_issue_type. A value of the form A | B | C is an ordered list of alternatives — the first name the instance actually has wins (the subtask entry documents the established pattern and why: the subtask level is spelled Sub-task, Task or Subtarea depending on the instance).
Intersect with .agents/jira-workflows.json, the synced catalog of what the instance really exposes. A work type absent from that file does not exist here.
A declared type the instance lacks is SKIPPED WITH A NOTE in the sprint plan.md §Risks. It is never a blocker and never a reason to stop.

The JQL is then built from the surviving names plus the sprint filter. Illustrative only — do NOT copy this list into the plan or any reference: on an instance that happens to expose all six coverable types, step 4 yields sprint = {N} AND project = {{PROJECT_KEY}} AND issuetype in (Story, Bug, Defect, Improvement, "Tech Story", "Tech Debt"). On an instance with only Story it yields issuetype = Story, and that is a correct, complete run.

Execute it with bun run jira:sync-issues jql "<query>" (resolves every slug and materializes the per-issue .md), or pull --sprint <N> --types <csv> for the same roster.

Workflow — one pipeline for all modes

Session Start (always first)
    -> PBI folder + context.md · session dir + test-session-memory.md
    -> Story explanation, WAIT for user OK

Stage 1 — Planning
    -> For Story: triage risk + Test Analysis + ATP/ATR + TC OUTLINES (names + 1-line precond/expected)
                  jira-native -> NO `Test` work items here (created in Stage 4, regression-worthy only)
                  jira-xray   -> Set-first order (see "Stage 1 Set-first order" below): ① CREATE +
                                 EXECUTE `Test` issues at executable detail + the Story's ATS (Test
                                 Set) created/updated holding ALL of them ② ATP item find-or-created
                                 FROM the {{jira.acceptance_test_plan}} field content ③ ATP/ATR test
                                 lists DERIVED from the ATS membership ④ ATR always created WITH the
                                 Test Environment.
                                 Stage 4 promotes the regression-worthy ones into the Regression Test Plan.
    -> For Bug:   veto check + Bug Analysis + ATP/ATR.
                  jira-xray   -> ONE repro `Test` by default, created at fix-verification time (1:N
                                 only if the scope genuinely covers distinct conditions — justify per
                                 test-design-doctrine), executed in the retest Execution, PASSED/FAILED
                                 recorded. Bug↔Test linked via the `test` slug (Bug is coverable).
                  jira-native -> no TCs in-sprint (the bug IS the immediate retest case; defers to
                                 Stage 4). If regression-worthy, Stage 4 ensures a persistent Test
                                 covers it — REUSE the existing failed Test or CREATE one (golden
                                 rule; both modalities).
    -> See references/acceptance-test-planning.md and references/feature-test-planning.md
    -> TC work-item timing rule -> see "TC creation timing (modality-aware)" below

Stage 2 — Execution
    -> Smoke test is always first (Go / No-Go)
    -> Then UI / API / DB exploration per what changed
    -> Evidence into .context/PBI/epics/EPIC-<KEY>-<slug>/stories/STORY-<KEY>-<slug>/evidence/
    -> See references/exploration-patterns.md

Stage 3 — Reporting
    -> Fill ATR, post QA comment, transition ticket
    -> File bugs via bug-report template when found
    -> See references/reporting-templates.md

---> Hand off (cross-skill, NOT this skill):
       Stage 4 -> test-documentation
       Stage 5 -> test-automation

### TC creation timing (modality-aware) — AUTHORITATIVE

> Resolves the one question that decides this skill's whole shape: *when does a test case become a work item in the TMS?* Guiding principle: **a test is persisted into the REGRESSION repository because it will be re-executed (manual or automated), never to hit a count.** The mechanism differs by modality because the TMS tools differ — an Xray `Test` issue is an **execution unit**, a Jira-native `Test` issue is **documentation**.

**Key distinction:** an **execution artifact** (how you run + record a test this sprint) is NOT the **regression repository** (the curated set of repeatable tests). The principle governs the repository, not the sprint execution artifacts.

| | **Modality jira-native** | **Modality jira-xray** (`bun xray` CLI) |
|---|---|---|
| Stage 1 (Planning) | TC **outlines only** (names + 1-line precond/expected in the ATP). **No `Test` work items** — a native `Test` issue IS documentation, so it waits for the Stage-4 regression-worthy gate. | **ASK the format once per batch** (see "Test-case format — ask once per batch" below), then **create + execute** Xray `Test` issues for the **planned outlines**, at *executable* detail (preconditions + runnable steps), and run them via a **Test Execution** — all in one pass. By Xray's plugin design the `Test` is the execution unit, so generating these artifacts is what makes the rest of the Xray flow work. All created Tests are aggregated into the Story's **ATS** and the Plan/Execution lists derive from that membership (see "Stage 1 Set-first order" below). **Manual** tests are created **without inline steps**, then steps are added one-by-one (see "Manual Xray test steps — two-step creation"). |

#### Test-case format — ask once per batch (Modality jira-xray, Stage 1) — AUTHORITATIVE

Before creating the batch of Xray `Test` issues, **ASK THE USER ONCE PER BATCH** which test-case format to use, and apply the chosen format to **the whole batch**:

- **Manual** — Xray `type=Manual`; step / data / expected-result steps (human-readable, no Gherkin).
- **Gherkin / Cucumber** — Xray `type=Cucumber`; Scenario / Scenario Outline + Examples.

Default *suggestion* (the user still picks): **Gherkin** for automation-candidate flows, **Manual** for exploratory / human-judgment scenarios. State the suggestion, then wait for the user's choice — do not auto-pick. This Stage-1 ask is a sprint-execution convenience; it does NOT pre-empt the Stage-4 ROI verdict→format mapping in `test-documentation` (Candidate→Gherkin, Manual→Manual), which governs the **persistent regression** repository.

#### Manual Xray test steps — two-step creation (Modality jira-xray) — AUTHORITATIVE

Xray Cloud **silently drops** steps passed inline to `test create`. So whenever the batch format is **Manual**, create each Test in **two steps**, never inline:

1. **Create** the `Test` (`type=Manual`) WITHOUT inline steps — `[TMS_TOOL] Create Test: type=Manual, title=...` (no `steps=`).
2. **Add each step one-by-one** via `[TMS_TOOL] Add Test Step` (action / data / expected per step) — the `/xray-cli` skill carries the concrete CLI syntax.

Optionally **verify** with `[TMS_TOOL] Get Test` that the steps landed. Gherkin/Cucumber Tests are unaffected (the Gherkin is one field) — this two-step rule applies to **Manual** tests only.

#### Stage 1 Set-first order (Modality jira-xray) — AUTHORITATIVE

The Story's coverage backbone is its **ATS** (Acceptance Test Set — `ATS: {US_ID}: {story title}`, `{US_ID}` = the Story key; mandatory per Story, even with a single TC). Stage 1 runs in THIS order:

1. **ATS holding ALL the Story's TCs.** Create the sprint `Test` issues, then create/update the Story's ATS (parent: **QA Test Artifacts** epic; **components inherited from the Story — mandatory**) with ALL of them as members, and link **ATS→Story** via the `test` slug (`{{jira.link_types.test}}`, Story `is tested by` ATS). This link is what fills the Xray coverage panel (live-verified); the ATP→Story and ATR→Story links are administrative traceability only and contribute ZERO coverage.
2. **ATP item FROM the field (find-or-create).** Pre-sprint the ATP lives ONLY in `{{jira.acceptance_test_plan}}` — the shift-left pass is field-first and does NOT create the item. Find-or-create the Test Plan issue `ATP: {STORY-KEY}: {story title}` (parent: **QA Master Test Plan** epic) and seed its description from the field content; if the field is empty (no shift-left pass), author the ATP normally and write both the item and the field.
3. **Derive, never re-list.** The ATP's test list and the ATR Execution's test list are DERIVED from the ATS membership — never maintained as three independent id lists.
4. **ATR always with environment.** Create the ATR Execution (`ATR: {STORY-KEY}: Story Testing`, parent: **QA Test Artifacts**) ALWAYS carrying the Test Environment resolved from `active_env` in `.agents/project.yaml` (or the session env switch). **No ATR without environment** — hard gate: `agentic-qa-core/references/stage-gates.md` §Stage 1.

TC∈ATS / TC∈ATP / TC∈ATR membership is Xray-internal (GraphQL) — NEVER expressed as Jira issue links in this modality. In jira-native, an instance WITH the Test Set work type expresses membership as `TC→ATS` issue links (explicit carve-out from the no-membership-links rule, which is xray-only); an instance WITHOUT it has no ATS — fall back to direct `TC→Story` links.

Intended stage asymmetry (not drift): in-sprint Stage 1 creates the TCs first and groups them into the ATS incrementally as they land, while Stage 4 module-driven (`test-documentation`) pre-creates the containers before the first TC because parallel sharding needs the targets to exist.
| Stage 2 (Execution) | Run planned outlines **+ explore beyond them**; track outline status (PASS/FAIL) in `test-session-memory.md`. | Execute the created Tests in the Test Execution; **explore beyond them**. A throwaway exploratory probe becomes a `Test` ONLY if it found a defect or is worth repeating — otherwise it stays as session evidence / a bug, NOT a `Test` (avoid one-shot-Test explosion). |
| Stage 4 (`test-documentation`) | **Create** `Test` work items **only for regression-worthy** scenarios (Candidate/Manual) after ROI; apply the feature/Epic label (native's organizer — no Test Set entity). Deferred → report only, no TMS `Test`. | **Select + promote**: from the sprint Xray Tests, the regression-worthy ones (Candidate/Manual) get **enriched** (rich Gherkin, parameterization, edge elaboration), **labelled** `regression-candidate`, **added to the feature Test Set** (1:1 Epic, created lazily if missing) **and the Regression Test Plan**. Deferred sprint Tests stay tied to their Test Execution as historical record — **not promoted, not deleted**. |

**Invariants (both modalities):**
- The **persistent regression set** is ROI-gated in Stage 4, never assumed in Stage 1.
- The wide 1:N technique derivation feeds the ATP outlines + execution — in native it stays as outlines; in Xray it materializes as sprint `Test` artifacts. Either way it does NOT auto-populate the regression repository.
- Heavy specification ("specify much more") is spent only on Stage-4 regression candidates, never on Deferred scenarios.

See `agentic-qa-core/references/test-design-doctrine.md` (derive widely) + `test-documentation` Three-Outcomes (persist narrowly).
       Stage 6 -> regression-testing

Session-start is the universal entry. Single-issue mode runs the same 4 dispatches as sprint-wide: Session Start -> Stage 1 -> Stage 2 -> Stage 3. The orchestrator dispatches them sequentially (each subagent's report feeds the next briefing's "Context docs"). The full briefings live in references/sprint-orchestration.md. Use them verbatim — do NOT inline any stage just because there is only one issue. Sprint-wide loops these same four dispatches through the PENDING rows of the sprint plan.md queue and, after each issue closes, appends one entry to the sprint progress.md and one comment to the STP.

Readiness Preflight Gate (MANDATORY — runs before Phase 0)

Full doctrine: agentic-qa-core/references/preflight-gate.md. Runs FIRST, before the resume check. Two laws: (1) args-as-answers — "QA UPEX-123 on staging" already answers env + scope; "test the login API" already answers the surface (API). Ask only the gaps. (2) probe, don't assume — a configured MCP is RED until it actually answers. Surface gaps + REDs as ONE AskUserQuestion checklist; self-fix with approval + explanation; STOP on any blocking RED. This is the heaviest gate in the repo because Stage 2 exercises UI + API + DB live. Generic baseline (env resolution, test-user creds, secret/restart handling, the two laws, output contract) is inherited from the reference §3.1 — not repeated here. Below is only this skill's specific capability delta.

Capability	Need	Why here
Framework adapted (artifacts present)	REQUIRED	Live QA needs the project wired — `{{WEB_URL}}` / MCP names are `null` on a generic boilerplate. Probe the reference §4 ADAPTED signals; still generic → STOP and tell the user to run `/project-discovery` → `/adapt-framework` themselves. The gate NEVER auto-runs them.
Active env reachable	REQUIRED	Authoring an ATP against a dead env is the highest-cost waste. Probe `{{WEB_URL}}` + `{{API_URL}}` root. This subsumes the env half of Session Start §0.6 — pulled to t=0.
Test-user credentials + roles	REQUIRED	`<<ACTIVE_ENV>>` creds in `.env`. Ask how many roles the ticket needs; one token per role via `scripts/api-login.ts`.
Issue-tracker (`[ISSUE_TRACKER_TOOL]`) + TMS modality	REQUIRED	All ATP/ATR/QA-comment/transition writes go to Jira. Load `/acli`; resolve modality; load `/xray-cli` + `XRAY_*` if jira-xray.
OpenAPI MCP (schema read-only)	SCOPE — when API surface is in scope	The `openapi` MCP is schema-read-only — discover endpoints + read schemas (`list-api-endpoints` / `get-api-endpoint-schema`); it does NOT execute authenticated requests. Probe that a schema call returns the spec. Generic/unset spec → `/adapt-framework`. Execution is curl's job (next row).
API token for curl (`bun run api:login`)	SCOPE — when API execution is in scope	Authenticated requests run via curl, not the MCP. Mint: `bun run api:login [<env>] [--role <role>]` → `.auth/tokens.env`. Execute: `source .auth/tokens.env && curl -H "Authorization: Bearer $API_TOKEN_<ROLE>_<ENV>" "$API_BASE_URL/<path>"`. No restart needed (the token never enters an MCP). Canon: `agentic-qa-core/references/api-testing-doctrine.md`.
DBHub MCP	SCOPE — when DB validation is in scope	The trifuerza DB leg. Probe `dbhub` lists schema/tables; `DBHUB_*` in `.env`. Unset → user fills `.env` + RESTART (spawn-time).
Playwright / `/playwright-cli`	SCOPE — when UI surface is in scope	Smoke + UI exploration. Browser present (`bun run pw:install` if not).
Email (`resend`) — can RECEIVE	SCOPE — magic-link / auth-token tickets only	Subsumes the inbox half of Session Start §0.6. A send-only provider cannot complete a magic-link flow → STOP before Stage 1.
`kata-manifest.json`	OPTIONAL	Only load-bearing at the Stage 3 → `/test-automation` handoff (anti-duplication).

Surfaces (UI / API / DB / code-review-only) are decided by Stage 1 Planning's triage + veto + risk-scoring — NEVER asked of the user (reference §5). The gate only probes and reports which surface tools are ready; Stage 1 reads that report and picks the trifuerza subset on its own. A scope-conditional tool stays REQUIRED only once Stage 1 selects its surface — if RED then, surface the remedy at that point. Session Start §0.6 stays as written — this gate is its t=0 generalization, not a replacement. After the gate clears (generic baseline + any already-evident surface tools GREEN), continue to Phase 0 below.

Phase 0 — Session resume check (MANDATORY, inline)

Before Session Start dispatch, run the resume contract from agentic-qa-core/references/session-management.md §4:

Compute prospective <scope> from the mode answer: <JIRA-KEY> (single-issue) or sprint-<N> then sprint-<N>/<JIRA-KEY> (sprint-wide — see the two-altitude note below).
Check .session/sprint-testing/<scope>/progress.md.
If it does NOT exist → proceed to Session Start (writes plan.md).
If it DOES exist:
- Read plan.md + tail of progress.md.
- Optionally read .session/sprint-testing/<scope>/test-session-memory.md for the per-issue domain state (load-bearing across the 4 sub-agent dispatches; issue altitude only).
- Surface to the user: last completed stage (Session Start / Stage 1 / Stage 2 / Stage 3) — or, at sprint altitude, the last closed issue and the next PENDING one — plus any unresolved BUG_FOUND or TOOL FAILURE from the last entry.
- Offer resume / restart / abort. On restart, archive to .session/.archive/<YYYY-MM-DD>-sprint-testing-<scope>-aborted/ first.

Sprint-wide runs Phase 0 twice over, at two altitudes (agentic-qa-core/references/session-management.md §9 "Nested scopes"):

Once on sprint-<N> at sprint entry. Existing pair → the resume summary is "queue of {n}, {k} closed, next is <KEY>". No pair → Session Start §0.5 builds it.
Then once per issue on sprint-<N>/<JIRA-KEY>, as the loop enters that issue (NOT once at sprint-loop entry). Per-issue resume keeps sprint progress fine-grained.

restart at sprint altitude archives the whole sprint-<N>/ tree, nested sub-scopes included — never offer it while an issue is mid-flight.

Session Start — the universal entry

Every invocation starts by initializing the session, even in sprint-wide mode. Session Start:

Resolve TMS modality (Xray on Jira vs Jira-native). By excellence ATP/ATR/ATS are real Jira items — a Test Plan issue (ATP: {STORY-KEY}: {story title}) parented to the QA Master Test Plan epic, a Test Execution issue (ATR: {STORY-KEY}: Story Testing) parented to the QA Test Artifacts epic, and a Test Set issue (ATS: {US_ID}: {story title}, the Story's coverage backbone) also parented to QA Test Artifacts; the Story custom-field + comment mirror (Modality jira-native) is a fallback ONLY when those work types are unavailable. Pre-sprint the ATP lives ONLY in the {{jira.acceptance_test_plan}} field — Stage 1 is where the Test Plan item is born (find-or-create from the field). The modality probe decides which path is live. Title grammar + epic parenting + the Feature-altitude FTP name: references/acceptance-test-planning.md. Full resolution algorithm lives in test-documentation/SKILL.md §Phase 0 — apply the same four-step probe here (AGENTS.md -> master-test-plan.md -> list issue types -> ask the user). Persist the result into test-session-memory.md. 0.1. Load required tool skills — based on the TMS modality resolved in Step 0:

Always load /acli (Jira WRITE operations: comment, transition, link, custom-field update, bug creation). Detailed READS (ACs, ATP/ATR, description, comments) do NOT use /acli — they use bun run jira:sync-issues get <KEY> --include-comments then read the synced .md. See agentic-qa-core/references/acli-integration.md §"Reads vs writes".
In Modality jira-xray: also load /xray-cli for Test / Test Execution / Test Plan / Test Run operations and traceability reads.
In Modality jira-native: /acli covers [ISSUE_TRACKER_TOOL] writes and [TMS_TOOL] operations — no additional skill needed. Detailed reads still route through the sync script. This step is mandatory before any pseudocode block below executes. The skills carry the concrete syntax, flags, and JSON payloads this skill intentionally omits. 0.5. Sprint session pair (sprint-wide mode only — skip in single-issue mode):
The mode came from the §"The mode question" ask, not from guessing at the invocation wording.
Phase 0 already checked .session/sprint-testing/sprint-<N>/progress.md. Act on what it found:
- Missing -> build the pair before entering the issue loop: resolve the JQL scope (§"Sprint scope is a JQL query"), write plan.md per agentic-qa-core/references/session-management.md §6, and open progress.md with its frontmatter. Procedure: sprint-orchestration.md §Part 1 — Sprint plan + STP.
- Present -> resume against it. plan.md is NOT regenerated on a schedule: it is the sprint's agreement, and a wholesale rewrite would silently destroy hand-written wave notes and assignments. Newly-arrived issues are appended to the queue and the change is recorded in ## Changelog (append-only, §6).
Single-issue and bug-only invocations skip this step entirely — they own no sprint-altitude state. 0.6. Environment + inbox preflight (orchestrator-inline, blocking gate — runs BEFORE Stage 1 authors any ATP):
Probe the active environment for reachability: a generic HTTP request to {{WEB_URL}} and {{API_URL}} root (HEAD or GET, e.g. curl -sI {{WEB_URL}}). Expect a 2xx/3xx (a login redirect counts as reachable). A hard failure on root — 404 / 410 / 5xx, connection refused, or a dead-deployment page (DEPLOYMENT_NOT_FOUND etc.) — means the env is not testable.
On hard failure: STOP and surface to the user before Stage 1. Do NOT dispatch the Session Start subagent and do NOT author an ATP against a dead env — that is the single highest-cost waste in a run. Offer the user a session env override (see Gotcha 15) if they have a working alternate URL.
Inbox receive-check (only when the ticket is email / magic-link / auth-token dependent — inferred from the invocation, ticket type, labels, or title): confirm the configured mailbox/provider can actually receive, not just send. A send-only provider (e.g. a domain configured for outbound only) cannot complete a magic-link flow. If it cannot receive, STOP and surface before Stage 1.
This is a reachability gate (is the env even up? can we get the email?), distinct from the Stage 2 smoke test (does the feature work?). Both run; they answer different questions — keep anti-pattern S7 and the smoke pass as-is. 0.7. Sprint Test Plan (STP) find-or-create (orchestrator-inline; sprint-wide mode ONLY — fires on the FIRST ticket of the sprint. In single-issue mode SKIP this step entirely: that mode owns no sprint-altitude state and creates no STP, per the scope table above):
Resolve N from the ticket's Sprint field: bun run jira:sync-issues get <KEY>, then read the sprint value in the generated .md (the script also accepts --sprint <active|current|closed|>=N|7,8,10> and the JIRA_SYNC_SPRINTS env default — that is the sprint-wide path, resolving N once for a whole sprint pull). Issue carries NO sprint → ASK the user for N; never guess or invent it.
Search for STP: Sprint#{N}: {objective} — a Test Plan item parented to the QA Master Test Plan epic.
Missing → create it (find-or-create; /regression-testing creates it as fallback if it runs suites first). Present → UPDATE it: the STP is a LIVING sprint planner — append this ticket to its scope and keep progress current after every tested ticket.
It closes at sprint end; the sprint recap Execution STR: Sprint#{N}: Regression Testing (parent: QA Test Artifacts) is created at sprint close — sprint-wide close recap or /regression-testing, whichever arrives first creates it, the other completes it (see references/sprint-orchestration.md §STEP 7).
Modality jira-native without the Test Plan work type: skip with a note (there is no field fallback at sprint altitude); non-blocking.

STP maintenance under concurrent testers (BINDING). The sprint session pair and the STP issue are the same artifact at two addresses, and the split is exact:

Local file	STP surface	Write mode	Writers
`plan.md`	the issue description	rewritten wholesale	ONE — whoever plans the sprint
`progress.md`	the issue comments	append-only, both sides	every tester

A description is replaced on each write, so two people editing it clobber each other; a comment is added, so two people commenting never can. That is the whole reason the pair is split this way. Read-first before touching the description (never overwrite someone's scope edit), and when an issue closes append ONE comment carrying the same content as that issue's progress.md entry. When the comment log and a Story's ATR disagree, the ATR wins — the ATR is the artifact of record; the comment is a running log that can lag or be written from stale state. No new tooling is needed to read the log back: bun run jira:sync-issues get <STP-KEY> --include-comments already materializes it locally.

Fetches the ticket via bun run jira:sync-issues get <KEY> --include-comments (title, ACs, priority, comments), then reads the synced .md files under the STORY folder. NEVER acli workitem view for custom fields.
Extracts Team Discussion from the synced comments.md (decisions, tech notes, edge cases, blockers). Non-blocking.
Loads the project-wide context files: .context/business/business-data-map.md, .context/business/business-feature-map.md, .context/business/business-api-map.md, .context/master-test-plan.md.
Loads module-context.md (3-level hierarchy: project -> module -> ticket) if the sync materialized it; if absent, drafts the body and publishes it into the Epic description's ## Module Context (QA) section (read-first, never overwrite), then re-syncs — the local file is Jira-synced, never authored by hand (see references/session-entry-points.md Step 4).
Explores backend ({{BACKEND_REPO}}) + frontend ({{FRONTEND_REPO}}) code.
Finds test data candidates via [DB_TOOL] on {{DB_MCP}}.
Creates the PBI folder and the session directory:
```
.context/PBI/epics/EPIC-<KEY>-<slug>/stories/STORY-{{PROJECT_KEY}}-{number}-{brief-title}/
  context.md                # hand-authored: session notes + open questions (NON-Jira, local-only)
  evidence/                 # screenshots (NON-Jira, local-only)

.session/sprint-testing/<scope>/
  test-session-memory.md    # hand-authored: shared memory across the 4 sub-agent dispatches
```
Jira-mirrored files (story.md, acceptance-criteria.md, acceptance-test-plan.md, acceptance-test-results.md, comments.md, etc.) are NOT hand-written here — they are materialized by bun run jira:sync-issues get <KEY> --include-comments.

The whole PBI tree is gitignored (it is a Jira cache; see AGENTS.md §9), so context.md and evidence/ are local-only by construction. test-session-memory.md lives in .session/ instead because a re-sync rewrites the PBI cache wholesale and this file is what every resume and every sub-agent reads.
Writes the session plan.md at .session/sprint-testing/<scope>/plan.md per agentic-qa-core/references/session-management.md §6 — Goal (one sentence per ticket), Inputs (PBI paths + TMS modality + Team Discussion summary), Approach (mode + per-stage dispatch pattern), Phase breakdown (Session Start / Stage 1 / Stage 2 / Stage 3 with dispatch pointer + exit condition), Risks (from triage), Verification checklist, Cross-references (cites context.md, test-session-memory.md, acceptance-test-plan.md, acceptance-test-results.md).
Writes a Story Explanation and STOPS for user confirmation. Do not proceed until the user OK's.
After OK, appends the first progress entry ## Session Start — <ts> with status: completed, next: Stage 1 — Planning to .session/sprint-testing/<scope>/progress.md.

Details, templates and error table live in references/session-entry-points.md.

Mode branches — what changes after Session Start

Both single-issue and sprint-wide modes run the SAME 4-dispatch cadence (Session Start -> Stage 1 -> Stage 2 -> Stage 3) per issue. Use the briefings in references/sprint-orchestration.md §"Sub-agent prompt templates" verbatim — do NOT inline a stage just because there is only one issue. The previous "single-issue inline" path is REMOVED. The notes below describe only what is different per issue type or per mode (TMS payload shape, when the sprint log is appended, etc.). The dispatch sequence itself is invariant.

single-issue, User Story (Stages 1 -> 2 -> 3)

Run the same 4 dispatches. Per-stage payload differences:

Stage 1 (per "TC creation timing"): Triage risk -> Test Analysis -> ATP/ATR -> jira-native: TC outlines only, no Test work items; jira-xray: ask the TC format once per batch (Manual vs Gherkin), then create + execute Test issues for the planned outlines at executable detail via a Test Execution (Manual tests = create-then-add-step, per "Manual Xray test steps — two-step creation"). Persistent regression TCs are created (native) / promoted (xray) in Stage 4. Traceability (jira-xray) — Set-first (per §"Stage 1 Set-first order"): ① the Story's ATS (ATS: {US_ID}: {story title}) created/updated holding ALL the created TCs, linked ATS→Story via the test slug — the coverage link ② ATP item find-or-created FROM the {{jira.acceptance_test_plan}} field ③ ATP/ATR test lists DERIVED from the ATS membership ④ ATR created WITH the Test Environment (active_env). ATP→Story / ATR→Story links stay as administrative traceability; do NOT link TCs directly to the Story (last-resort only, for instances with no Test Set work type — see Gotcha #9). Verify with [TMS_TOOL] trace.
Stage 2: Smoke test -> UI / API / DB exploration beyond the planned outlines -> update outline status (native) or Test runs in the Test Execution (xray) PASSED / FAILED -> fold any newly-discovered partition/boundary/transition back into the outline set; an exploratory probe becomes a Test only if it found a defect or is worth repeating -> file bugs if any.
Stage 3: Author ATR Test Report -> apply the modality branch (reporting-templates.md §2.3-2.4): Modality jira-native -> write the {{jira.acceptance_test_results}} field (or ## Acceptance Test Results (ATR) fallback comment) then jira:sync-issues get <KEY> --include-comments -> acceptance-test-results.md in the STORY folder; Modality jira-xray -> update the Test Execution then jira:sync-issues get <ATR_KEY> -> .context/PBI/test-executions/ATR-<ATR_KEY>-<slug>.md (acronym prefix = conforming ladder title; a non-conforming title keeps the legacy TESTPLAN- / TESTEXEC- / RETESTEXEC- prefix) -> QA comment via [ISSUE_TRACKER_TOOL] -> transition ticket.
Per-stage progress checkpoint: after each Stage subagent returns, the orchestrator appends a phase entry to .session/sprint-testing/<scope>/progress.md per agentic-qa-core/references/session-management.md §7 (status: completed, dispatched_as: Sequential, next: Stage <N+1> | hand-off).
Archive after Stage 3: when Stage 3 completes (or veto-skip Code-Review variant finishes), the orchestrator moves .session/sprint-testing/<scope>/ to .session/.archive/<YYYY-MM-DD>-sprint-testing-<scope>/ and calls mem_session_summary per agentic-qa-core/references/session-management.md §8. PBI artifacts under .context/PBI/ stay.
Afterwards: hand off to test-documentation for ROI + Stage 4.

single-issue, Bug (Triage -> Verify -> Report)

Run the same 4 dispatches; the Stage 1 briefing additionally applies the veto + risk-score decision tree before producing the ATP.

Triage: veto table (see Gotchas) -> if SKIP, run Code-Review workflow and finish (Stage 2 + Stage 3 dispatches collapse to the in-place comment + transition; the orchestrator skips them only if the Stage 1 subagent reports veto_outcome: skip).
Risk score only if no veto applies. 0-3 LOW, 4-7 MEDIUM (ask user), 8+ HIGH.
Create ATP + ATR (the ATR is the retest Execution ReTest: {BUG_KEY}: {summary}, ALWAYS created with the Test Environment from active_env — no ATR without environment). Fill Bug Analysis inside the ATP.
Repro Test (Modality jira-xray only): create ONE repro Test by default, at fix-verification time (Stage 2) — 1:N only if the bug's scope genuinely covers distinct conditions (justify per agentic-qa-core/references/test-design-doctrine.md). Link Bug↔Test via the test slug ({{jira.link_types.test}}, Bug is tested by Test — bugs are coverable), execute it in the retest Execution and record PASSED/FAILED. Modality jira-native: unchanged — no TCs in-sprint (the bug is the immediate retest case); persistent-Test decisions defer to Stage 4.
Regression follow-up: if the bug is regression-worthy, Stage 4 (test-documentation bug-driven decision) ensures a persistent Test covers it — reuse the existing failed Test (or the in-sprint repro Test) or create one (golden rule). Not every bug qualifies; a one-time typo in a stable area is treated like a failed test.
Execute: reproduce original bug -> verify fix -> regression pass on adjacent areas -> DB cross-validation if data-integrity bug.
Report: update ATR, post comment (Template C PASSED or Template D FAILED), provide 1-2 evidence screenshot paths to the user.

sprint-wide

Pre-step: build the sprint session pair if it does not exist — plan.md (the local STP: JQL-resolved queue, waves, assignment) + an empty progress.md — and find-or-create the STP issue from it (see sprint-orchestration.md §Part 1).
Loop: read the plan.md queue for the first PENDING row, dispatch the same 4-stage sequence per issue, then append one entry to the sprint progress.md + one comment to the STP + present a per-issue summary + wait for user OK.
Interrupted session resume: Phase 0 runs at both altitudes — once on sprint-<N>/progress.md at sprint entry (answers "how far did this sprint get?"), then per issue on sprint-<N>/<ISSUE>/progress.md (canonical resume signal per agentic-qa-core/references/session-management.md §4). Domain state for an in-flight issue sits beside the latter in sprint-<N>/<ISSUE>/test-session-memory.md (load-bearing for the 4 sub-agent dispatches). The files serve different concerns: progress.md decides "which stage is next?"; test-session-memory.md carries the per-issue payload that each sub-agent reads. All survive a jira:sync-issues re-pull because none lives in the PBI cache.
After each stage subagent returns, the orchestrator appends a phase entry to the ISSUE's progress.md per agentic-qa-core/references/session-management.md §7. After Stage 3 completes, the orchestrator (a) appends ONE entry to the SPRINT's progress.md and mirrors it as one STP comment, then (b) runs Archive on the issue sub-scope: moves .session/sprint-testing/sprint-<N>/<ISSUE>/ to .session/.archive/<YYYY-MM-DD>-sprint-testing-sprint-<N>-<ISSUE>/ and calls mem_session_summary. The PBI artifacts under .context/PBI/ stay. The sprint pair is archived only at sprint close (§STEP 7), never while an issue is mid-flight.
Nothing local is a deliverable. .session/ is gitignored and exists only on this machine. The sprint's shareable record is the STP in Jira (description ← plan.md, comments ← progress.md) and the per-Story ATP / ATS / ATR items. Never tell the user a local file is the canonical output.
Stop on TOOL FAILURE. Pause on BUG_FOUND. Append the sprint progress.md entry ONLY after Stage 3 completes.

Gotchas — inline rules you must apply every invocation

Credentials: always from .env. Never hardcode. Never guess passwords.
PBI folder naming: canonical layout is .context/PBI/epics/EPIC-<KEY>-<slug>/stories/STORY-<KEY>-<slug>/ (module = Epic, 1:1). <slug> is max 5 words, kebab-case, AI-generated from the ticket title. Epic-level files live in the EPIC folder; story-level files in the STORY folder.
Bug TCs are modality-aware. Modality jira-xray: ONE repro Test by default, created at fix-verification time (1:N only when the bug's scope genuinely covers distinct conditions — justify per agentic-qa-core/references/test-design-doctrine.md), linked Bug↔Test via the test slug, executed in the retest Execution with PASSED/FAILED recorded. Modality jira-native: ATP + ATR, no TCs in-sprint — the bug ticket is the implicit immediate test case; reproduction steps = test steps (defers to Stage 4). Either way a regression-worthy bug MUST end with a persistent Test in Stage 4 — reuse the existing failed Test (or the in-sprint repro Test) or create one (golden rule). Not every bug qualifies.
Smoke test is mandatory as the first action in Stage 2. If smoke fails (No-Go), stop and report — do not proceed to deep exploration. Smoke failure is an env-level blocker and always stops; deep-exploration findings follow the graduated rule in #10 (a FAIL mid-pass is not auto-Critical).
Bug veto table — SKIP retesting when the bug is pure text / CSS / docs / config / tech-debt cleanup with no functional change. REQUIRE retesting regardless of score when it touches money, data integrity, auth, external integrations, state machines, or calculations. Veto beats risk score.
TCs are created in Stage 1, NEVER in Stage 2. Stage 2 executes what Planning produced; new TCs found during exploration are added via [TMS_TOOL] tc create but the rule is "planning first".
Explain the story -> WAIT for OK. Never auto-proceed past Session Start without user confirmation. Same for bug triage — present the decision and wait.
Evidence directory: always configure .playwright/cli.config.json outputDir to .context/PBI/epics/EPIC-<KEY>-<slug>/stories/STORY-<KEY>-<slug>/evidence/ BEFORE using [AUTOMATION_TOOL]. Screenshots need the full path in --filename because outputDir does not apply to .png.
Traceability check after Stage 1 (Modality jira-xray): run [TMS_TOOL] trace {TICKET} and verify the Set-first model — the coverage backbone is the ATS: ATS: {US_ID}: {story title} linked to the Story via the test slug ("is tested by") and holding ALL the Story's TCs (Xray-internal membership, never issue links in this modality). Story↔ATP and Story↔ATR links exist as administrative traceability — they contribute ZERO coverage (live-verified). The ATP's and the ATR's test lists are DERIVED from the ATS membership. Individual TCs are NOT linked directly to the Story (last-resort only, for instances with no Test Set work type). So verify: Story↔ATS (test slug) + ATS membership complete + Story↔ATP, Story↔ATR (administrative) + Plan/Exec lists matching the ATS. Full doctrine: agentic-qa-core/references/traceability-linking.md + test-documentation/references/tms-architecture.md. Bugs: the repro Test links Bug↔Test via the test slug at fix-verification time; before that, traceability "gaps" for missing TCs are expected and OK.
Graduated stop/pause protocol: TOOL FAILURE -> stop, report, await user. Blocking BUG_FOUND (smoke/env down, data integrity, security-exploitable) -> pause, present bug, await decision; NEVER dispatch the next sub-agent while unresolved. Non-blocking finding (cosmetic, minor validation, edge-case on a non-critical TC, framework-default pending recalibration) -> the Execution subagent logs it and CONTINUES the pass; the orchestrator surfaces it at Stage 2 close. A FAIL is not auto-Critical — triage first (severity per references/reporting-templates.md §1.4; security/auth/framework-default recalibrated at §5.0). See references/exploration-patterns.md "Finding triage".
Sprint log timing (sprint-wide): append the sprint-altitude progress.md entry — and its mirror STP comment — only AFTER Stage 3 completes and the orchestrator-side checklist verifies. Not earlier. progress.md is append-only in both directions: never rewrite an entry, never edit a posted comment; a correction is a NEW entry and a NEW comment. There is no local sprint tracker file to update — that artifact is retired.
Language: all artifacts, TMS content, and commit messages in English. Mirror the user's language only in conversation.
Environment + inbox preflight before ATP: Session Start §0.6 probes {{WEB_URL}} / {{API_URL}} for reachability (and, for email/auth-dependent stories, that the inbox can receive) BEFORE any ATP/Jira write. A dead env or send-only inbox is caught here with a STOP, not at Stage 2 after the ATP is already authored. Reachability gate ≠ Stage 2 smoke — see S7.
Severity recalibration before blocking a Story: a Story TC FAIL is NOT automatically a blocking defect. When the failing TC is security/auth/framework-default class (cookie flags, CSP/HSTS headers, SDK-by-design behavior), run the recalibration gate (references/reporting-templates.md §5.0) BEFORE firing {{jira.transition.story.defect_reported}}/blocked: state the framework-default/mitigation hypothesis, cite one verification fact, surface to the user. A recalibrated finding becomes GO-with-debt (PASSED WITH ISSUES), not a blocker. Mechanical path stays the default for ordinary functional FAILs. Once the gate confirms a real blocking defect and the defect_reported → blocked transition fires, also create the Story is blocked by Bug issuelink via {{jira.link_types.blocks.name}} (the Bug blocks the Story) — methodology step in references/reporting-templates.md §5.1, mechanics in agentic-qa-core/references/traceability-linking.md (§2/§4/§6). The status transition alone does not record the dependency edge.
Session env override: to test against an ad-hoc URL not in .agents/project.yaml (broken staging, ephemeral preview deploy, hotfix branch URL), record it ONCE in test-session-memory.md §Environment as WEB_URL_OVERRIDE / API_URL_OVERRIDE. When set, it beats the project.yaml active-env value for every stage and is read automatically by all four dispatches — never re-thread it per briefing, and never write it to project.yaml (session-only). Distinct from active_env switching, which picks a named env from project.yaml.
Session-footer contract (mandatory at close): the final stage is not done until the two chat-facing blocks from ../agentic-qa-core/references/session-footer-contract.md are printed: (1) consolidated screenshot list — repo-relative paths, verified on disk, bug annotations first — plus in-flow surfacing of every capture's path the instant it lands; (2) Session Footer listing skills/MCPs/CLIs actually used + testing levels touched, with explicit "none" entries for expected-but-untouched levels. Framing for this skill: execution. Multi-subagent sessions: each stage report carries the five footer fields (skills_loaded, mcps_used, clis_used, testing_levels_touched, screenshots_captured); the orchestrator compiles the footer ONCE at close. Chat only — never in a Jira comment or ATR body.

Cross-skill handoff — what this skill does NOT do

Predecessor	Load this skill	Reason
Pre-sprint AC refinement on a batch of backlog Stories	`shift-left-testing`	Stage 0. If the Story passed through `/shift-left-testing` and carries label `shift-left-reviewed` with a dated label <30 days old, Stage 1 here short-circuits Phases 1-3 of `acceptance-test-planning.md` and continues from Phase 4. The shift-left pass leaves the ATP in the `{{jira.acceptance_test_plan}}` FIELD only (field-first — no Test Plan item pre-sprint); Stage 1 finds-or-creates the item FROM that field. The short-circuit reads the SYNCED `acceptance-test-plan.md`. If the Story did NOT pass through Shift-Left, Stage 1 runs all phases in full — but this is more expensive in-sprint than pre-sprint.

After Stage 3 you need...	Load this skill	Reason
Formalize TCs in Jira/Xray, calculate ROI, decide Candidate / Manual / Deferred	`test-documentation`	Stage 4. This skill produces the inputs (outlines + execution evidence); `test-documentation` produces the formal regression backlog — creating `Test` work items (jira-native) or creating/promoting them into the Regression Test Plan (jira-xray), regression-worthy scenarios only.
Write the automated test code (KATA Page / Api + test file)	`test-automation`	Stage 5. Plan -> Code -> Review pipeline.
Run the regression or smoke suite in CI and emit a GO/NO-GO verdict	`regression-testing`	Stage 6. This skill's Stage 2 smoke is local-manual, not the CI suite.
Generate `business-data-map.md`, `business-feature-map.md`, `business-api-map.md`, `master-test-plan.md`	`project-discovery` (or the individual `/business-*-map` and `/master-test-plan` commands)	Sprint-testing consumes these; it does not create them.

If Session Start reports that any of the project-wide context files are missing, stop and hand off to project-discovery (or the relevant command). Do not continue without them.

Pseudocode tags used here

Tag	Resolves to	Defined in
`[TMS_TOOL]`	xray-cli skill, Atlassian MCP, or `{{TMS_CLI}}`	`AGENTS.md` Tool Resolution
`[ISSUE_TRACKER_TOOL]`	`acli`, Atlassian MCP, or `{{ISSUE_TRACKER_CLI}}`	`AGENTS.md` Tool Resolution

Reads vs writes split (per agentic-qa-core/references/acli-integration.md §"Reads vs writes"): detailed reads of an issue (custom fields, ACs, ATP/ATR, description, comments) use bun run jira:sync-issues get <KEY> --include-comments (or jql "<query>") then read the synced .md — NEVER acli workitem view (returns null for custom fields). Writes / transitions / links / bug creation / trivial summary-or-status lookups stay on [ISSUE_TRACKER_TOOL] (/acli). Traceability (link graph Story↔ATP↔ATR↔TC, Xray run status) stays on [TMS_TOOL] / /acli / /xray-cli — do NOT migrate trace reads to the sync. | [AUTOMATION_TOOL] | playwright-cli skill or Playwright MCP | AGENTS.md Tool Resolution | | [DB_TOOL] | DBHub MCP or Supabase MCP | AGENTS.md Tool Resolution | | [API_TOOL] | Schema read → OpenAPI MCP (read-only); execute → curl (token via bun run api:login) | AGENTS.md Tool Resolution + agentic-qa-core/references/api-testing-doctrine.md |

Concrete tools (bun, git, gh) are used literally. Project variables like {{PROJECT_KEY}}, {{DB_MCP}}, {{WEB_URL}} are resolved from .agents/project.yaml (env-scoped vars resolve to the active environment).

References — read the narrow one for the situation

All references are self-contained. Load one at a time.

Reference	Read when
`sprint-orchestration.md`	Running sprint-wide mode, building the sprint session pair + the STP, resuming a session, appending the sprint log, dispatching stage sub-agents, handling stop/pause/`continue-from`.
`session-entry-points.md`	Initializing a session (any mode), loading project + module context, creating the PBI folder + `context.md` and the session dir + `test-session-memory.md`, Team Discussion extraction rules, user-story workflow step order, bug Triage -> Verify -> Report workflow.
`acceptance-test-planning.md`	Stage 1 Planning — generating the ATP (Acceptance Test Plan) for a ticket, Test Analysis structure, TC nomenclature `{US_ID}: TC#: should <expected outcome> [<connector> <condition>] [given <precondition>]`, traceability creation + verification, and the Bug Analysis variant.
`feature-test-planning.md`	Stage 1 Planning at feature / multi-story level — building a feature test plan, risk triage rubric, scenario decomposition, and variable + test-data identification.
`exploration-patterns.md`	Stage 2 Execution — smoke-test Go/No-Go playbook, UI exploration on `{{WEB_URL}}`, API exploration on `{{API_URL}}`, DB cross-validation via `{{DB_MCP}}`, evidence naming + capture rules, edge-case checklist.
`reporting-templates.md`	Stage 3 Reporting — ATR Test Report body, bug report template (summary, reproduction, severity, priority, labels), QA comment templates (story PASSED/FAILED, bug Template C/D), evidence-attachment guidance.
`../agentic-qa-core/references/session-management.md`	Phase 0 + Session Start + per-stage checkpoints + Archive — resume contract, plan.md/progress.md schemas, archive policy, Engram per-phase checkpoint. This skill is a producer of `session/sprint-testing/<scope>/...` topic keys.

Anti-patterns — NEVER do these

S1. NEVER mark a Story Ready For Release (or transition to {{jira.status.story.qa_approved}}) without QA sign-off AND a signed-off ATR snapshot for audit trail.
S2. NEVER skip the Stage 1 Test Plan (ATP) step in Modality jira-xray workflows — the Xray Test Plan / Test Execution issues depend on the ATP being committed first; downstream TCs cannot link without it.
S3. NEVER push test results to Jira without an ATR snapshot. The QA comment is a summary; the ATR is the audit record.
S4. NEVER duplicate the ATR across Jira + Confluence (or any second store). Single source of truth — pick one per the modality decision in .context/master-test-plan.md and link from anywhere else.
S5. NEVER bypass the bug-triage decision tree (veto → risk-score → Severity + Root Cause) when a test fails. Every failure gets a triage before it becomes a Bug ticket.
S6. NEVER write ATP / ATR bodies in raw ADF JSON by hand. Use md-to-adf via [ISSUE_TRACKER_TOOL] so formatting survives Jira's renderer.
S7. NEVER skip the smoke pass before triforce (UI / API / DB) exploration. Smoke validates the environment; triforce validates the feature. Order matters — a broken env produces false-positive bug reports.
S8. NEVER mix UI + API + DB findings into a single bug ticket. File per layer (or per root-cause cluster) so triage and routing stay clean.
S9. NEVER reuse a PBI folder across tickets. Every Story or Bug gets its own .context/PBI/epics/EPIC-<KEY>-<slug>/stories/STORY-<KEY>-<slug>/ directory; cross-ticket contamination breaks evidence + traceability.
S10. NEVER transition the ticket Ready For QA → In Test without explaining the story to the user AND waiting for confirmation (AGENTS.md §8 — Session Start is not a one-shot, it's a hand-off gate).
S11. NEVER skip the auto-stage promote (Session Start → Stage 1 → Stage 2 → Stage 3) after a phase completes — each promote is a checkpoint that writes a progress.md entry and feeds the next subagent's Context docs.
S12. NEVER file a bug without a reproducible repro path AND evidence (screenshot, trace, log, network HAR, or DB row reference). "It failed for me once" is not a bug ticket.
S13. NEVER hardcode customfield_NNNNN IDs in ATP / ATR / QA comments or in any reference under this skill. Resolve every Jira field via {{jira.<slug>}} against .agents/jira-required.yaml.
S14. NEVER hand-write a Jira-mirrored .md in the PBI folder (story.md, acceptance-criteria.md, acceptance-test-plan.md, acceptance-test-results.md, comments.md, feature-test-plan.md, module-context.md, test-cases/, etc.). To SET their content: author it → write to the Jira custom field via [ISSUE_TRACKER_TOOL] (or, when the field is absent, a structured comment per .agents/jira-required.yaml fallback:; module-context.md goes to the ## Module Context (QA) section of the Epic description) → run bun run jira:sync-issues get <KEY> --include-comments → READ the materialized file. The whole PBI tree is gitignored, so a hand-written file there is invisible to every other machine. Only context.md and evidence/ are hand-authored inside PBI (local-only by design); test-session-memory.md is hand-authored under .session/sprint-testing/<scope>/.
S15. NEVER bury a hard-to-reverse test-architecture decision in a ticket plan. If Stage 1 planning forces a decision that is architectural AND hard to reverse (test-data-isolation contract, auth-in-tests change, fixture topology, flake-retry policy spanning 3+ tests or 2+ tickets), promote it to .context/ADR/ADR-NNNN-<slug>.md (append-only; supersede, never edit) and leave a See ADR-NNNN backlink in the plan's ## Technical Decisions. Ticket-local trade-offs stay in the plan. AI drafts Proposed; the human approves. See agentic-qa-core/references/adr-doctrine.md §1–§2.
S16. NEVER create an ATR / retest Execution without a Test Environment. The environment resolves from active_env in .agents/project.yaml (or the session env switch) and is set at creation time. An environment-less Execution fails the Stage-1 DoD gate (agentic-qa-core/references/stage-gates.md) — no ATR without environment.
S17. NEVER maintain the ATS's, the ATP's, and the ATR's test lists as independent id lists (Modality jira-xray). The ATS membership is the single source; the Plan and the Execution DERIVE their lists from it. Three hand-maintained lists drift silently and corrupt coverage.

Pre-flight checklist

Phase 0 — Session resume check ran (read .session/sprint-testing/<scope>/progress.md); user chose resume / restart / abort if prior state existed
Mode ASKED and answered (sprint-wide / single-issue) — never inferred from the invocation wording
Sprint-wide: .session/sprint-testing/sprint-<N>/plan.md written with the JQL-resolved queue; skipped work types noted, not treated as blockers
Session Start complete, user confirmed the story explanation
.session/sprint-testing/<scope>/plan.md written (per session-management.md §6 schema)
Project-wide context files present (if missing, hand off to project-discovery)
PBI folder + context.md created · session dir + test-session-memory.md created
.env credentials loaded (no hardcoded passwords)
Bug path: veto table evaluated BEFORE risk score
Sprint STP found-or-created (first ticket) / updated (Session Start §0.7; skip note if the work type is absent)
Stage 1 artifacts created with full traceability, verified via [TMS_TOOL] trace — jira-xray: Set-first order honored (ATP item from the field · ATS with ALL TCs linked to the Story via the test slug · Plan/Exec lists derived from the ATS membership)
ATR / retest Execution carries the Test Environment (active_env) — no environment, no ATR (S16)
Stage 2 smoke test executed FIRST, Go/No-Go recorded
Evidence captured under the ticket's evidence/ folder
Stage 3 ATR filled + QA comment posted + ticket transitioned
Per-stage progress checkpoint appended to .session/sprint-testing/<scope>/progress.md after each Stage subagent returned
Archive: .session/sprint-testing/<scope>/ moved to .session/.archive/<YYYY-MM-DD>-sprint-testing-<scope>/ and mem_session_summary called after Stage 3
Hand-off identified for Stages 4 / 5 / 6 if applicable
Sprint-wide: sprint progress.md entry appended + mirrored as ONE STP comment AFTER Stage 3 only, user OK'd the next issue
Session footer + consolidated screenshot list printed in chat per session-footer-contract (never in a Jira comment)