# Sprint Testing > Orchestrates in-sprint manual QA per issue across Stages 1 (Planning), 2 (Execution) and 3 (Reporting). Use for user-story testing, bug retesting, and sprint-wide QA loops. Creates the PBI folder, drives session-start, runs the triage + veto + risk-score decision tree on bugs, produces the ATP + ATR + TC artifacts in the TMS, executes smoke and trifuerza (UI/API/DB) exploration, and files the final QA comment + bug reports. Triggers on: test this ticket, QA this user story, retest this bug, verify bug fix, run exploratory testing, smoke test a feature, process the sprint, plan the sprint QA backlog, next ticket in sprint, resume sprint testing, continue-from a ticket. Do NOT use for Stage 4 TMS documentation + ROI (test-documentation), Stage 5 automation coding (test-automation), Stage 6 regression suite execution (regression-testing), or onboarding a new repo (project-discovery). - Skill: `upex-galaxy/sprint-testing` (Agent Skill, multi-file: 8 files) - Install (CLI): `npx skillmds@latest add upex-galaxy/sprint-testing` - Raw SKILL.md: https://api.skillmd.com/api/skills/upex-galaxy/sprint-testing/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - License: MIT - Author: upex-galaxy (https://skillmd.com/u/upex-galaxy) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/upex-galaxy/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 --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-/{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. 1. `.agents/project.yaml` — project identity, env URLs, `{{PROJECT_KEY}}`, MCP names, active environment. 2. `.agents/jira-required.yaml` — canonical slug catalog (custom fields, statuses, transitions) for the active workspace. 3. `.agents/jira-fields.json` — slug → numeric custom-field-ID mapping for `{{jira.}}` resolution at runtime. 4. `.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. 5. `.context/PBI/epics/EPIC--/stories/STORY--/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. 6. `.context/master-test-plan.md` — regression Epic pointer, modality decision (Xray vs Jira-native), what to test and why. 7. `.context/business/business-feature-map.md` — feature catalog vocabulary; resolves "what epic owns this story" for the `epics/EPIC--/` PBI folder naming (module = Epic, 1:1). 8. `.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. 9. The Story or Bug ticket itself — AC, ATP, comments — read via `bun run jira:sync-issues get --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`. 10. `.env` — `LOCAL_USER_*` / `STAGING_USER_*` credentials. NEVER hardcode; always read at runtime. 11. `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///`, 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/ ├── / # single-issue mode │ ├── plan.md progress.md test-session-memory.md └── sprint-/ # sprint-wide mode ├── plan.md # the local STP: scope, waves, assignment ├── progress.md # append-only sprint log, one entry per issue close └── / # per-issue sub-scope, identical to single-issue └── plan.md progress.md test-session-memory.md ``` **Single-issue** mode: `` = `` (e.g. `UPEX-123`). **Sprint-wide** mode: the sprint scope is `sprint-` and each issue's scope is `sprint-/`. 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-/` | found-or-created and kept current | `sprint-//`, one per issue | | `single-issue` | **not created** | **not created** (exactly as today) | `/` 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: 1. Read `.agents/jira-required.yaml` and take every work type declared `coverable: true`. 2. 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). 3. 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. 4. 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 ""` (resolves every slug and materializes the per-issue `.md`), or `pull --sprint --types ` 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--/stories/STORY--/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 | `<>` 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 [] [--role ]` → `.auth/tokens.env`. Execute: `source .auth/tokens.env && curl -H "Authorization: Bearer $API_TOKEN__" "$API_BASE_URL/"`. **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: 1. Compute prospective `` from the mode answer: `` (single-issue) or `sprint-` then `sprint-/` (sprint-wide — see the two-altitude note below). 2. Check `.session/sprint-testing//progress.md`. 3. If it does NOT exist → proceed to Session Start (writes `plan.md`). 4. If it DOES exist: - Read `plan.md` + tail of `progress.md`. - Optionally read `.session/sprint-testing//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/-sprint-testing--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-`** at sprint entry. Existing pair → the resume summary is "queue of {n}, {k} closed, next is ``". No pair → Session Start §0.5 builds it. - **Then once per issue on `sprint-/`**, 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-/` 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: 0. **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 --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-/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 `, then read the sprint value in the generated `.md` (the script also accepts `--sprint =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 — app …(truncated)