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: every coverable work type .agents/jira-required.yaml declares (work_types.*.coverable) is in scope, 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:

• Mode from $ARGUMENTS: a first token naming a mode (single-issue, sprint-wide) IS the mode and the rest is forwarded; otherwise ASK the mode question, never infer it.
• 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.
• QTU duty: when Stage 3 approves a Story (qa_sign_off to {{jira.status.story.qa_approved}}), write {{jira.quality_token_usage}} with the MEASURED tokens (thousands) the QA agent spent on the item; field absent → structured Jira comment, never block; harness exposes no figure → leave it empty and the verifier line says N/A with the reason. NEVER estimate or invent it.
• 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.
• Stage 1's Shift-Left short-circuit is fail-closed: the shift-left-reviewed + dated labels alone run the FULL flow. Phases 1-3 are skipped only on cited evidence: a pre-sprint ATP body in the synced acceptance-test-plan.md (or its ## Acceptance Test Plan (ATP) fallback comment), a dated label under 30 days old, refined ACs that still match the Story. Stage 1 never writes those labels or that field before the check (references/acceptance-test-planning.md §0.0).
• Execution = smoke pass first, then trifuerza (UI/API/DB) exploration; capture evidence under the PBI folder.
• A TC is PASSED or FAILED only when observed in the environment its precondition names; a unit test, green CI, a code read or another environment leaves it NOT RUN. NOT RUN runs the blocking ladder (recreate -> QA defers with a follow-up task -> developers -> owner if unsure) and is never recorded FAILED. Canon: agentic-qa-core/references/discovery-driven-doctrine.md §5.
• 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.
• Every role signs in through the app's own login only (UI form → .auth/<env>-<role>.json, or bun run api:login --role <role>). NEVER obtain a session through a service-role / admin key, an admin user-management API, a server-generated magic link or reset token, a locally signed JWT or a database session row; seeding test DATA through API / DB stays allowed. An auth story runs end to end through a real inbox (/resend-cli); production = dedicated synthetic QA accounts only. A check that seems to need a shortcut is a blocker to report. Canon: agentic-qa-core/references/browser-sessions.md §4.
• Consult business-domain-context (bun run context:map business-domain-context) 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.
• Before any step that uses a declared MCP capability (metadata.requires_capabilities: db, api-schema), run the point-of-use check in agentic-qa-core/references/preflight-gate.md §8: resolve by tool-name suffix, and when no available tool provides it STOP and name the capability + how to enable it, never a silent fallback.

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.<slug>}} resolution at runtime.
4. .agents/jira-workflows.json — workflow + transition catalog, the authoritative source of every status / transition name (resolves every status / transition slug). A status that is not in this file does not exist in the instance. 4b. agentic-qa-core/references/artifact-lifecycle.md — canonical authority for which status every artifact this skill creates must END in (ATP ready→completed, ATS designing→close, ATR active→close, TCs draft→ready), assignee-at-create on all of them, the unmapped-status fallback (§4), and the light stage verifier that closes each stage (§5). Read BEFORE firing any transition.
5. .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.
6. .context/PBI/qa-artifacts/master-test-plan.md — the Master Test Plan (cache of the QA Master Test Plan Epic description; missing → bun run context:hydrate): regression Epic pointer, what to test and why.
7. business-e2e-context (bun run context:map business-e2e-context) — the journeys the story sits in and the feature catalog vocabulary; resolves "what epic owns this story" for the epics/EPIC-<KEY>-<slug>/ PBI folder naming (module = Epic, 1:1). business-data-context and business-api-context join per touched level (DB / API), read the same way.
8. business-domain-context (bun run context:map business-domain-context; one term: --section term-<slug>) — canonical domain vocabulary; consult BEFORE authoring the ATP, refined ACs, and TC outlines so test names, entity terms, and Gherkin wording use canonical terms. If a new or ambiguous term surfaces during testing, flag it in the Stage 3 QA comment and PROPOSE the one-section edit through that skill's refresh path (applied only on approval) — NEVER hand-edit the map from a testing session.
9. 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.
10. .env — the test-user credentials config/variables.ts declares for <<ACTIVE_ENV>> (shipped example names: LOCAL_USER_* / STAGING_USER_*). NEVER hardcode; always read at runtime. Nothing requires them up front: config.testUser fails by name when a test reads an empty pair.
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 the business-domain-context map 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 §3 (Orchestration Mode) 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".

Modes are equivalent in dispatch shape. Single-issue mode runs ONE pass through these four dispatches. Sprint-wide loops them per issue. 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. The Fleet row above does not weaken this: it parallelizes ACROSS issues (each worker owns one issue end to end and runs these four dispatches Sequentially inside it), never the stages of one issue.

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

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. The one explicit answer is a first token of $ARGUMENTS that names the mode (/sprint-testing sprint-wide 12, /sprint-testing single-issue UPEX-123): that token IS the mode, the rest is forwarded, and the question is skipped. Otherwise ask, then apply:

Then, and ONLY for sprint-wide, ask the second question (skip it entirely for single-issue — one issue has one executor by definition):

Run the queue in this session (one executor), or fan it out to one session per issue (a fleet)?

Executors — the second axis (1 or N)

Mode is a scope, and scope is only half of the picture. What this skill runs is scope × executors:

N=1 is unchanged, byte for byte. Same queue, same waves, same dispatches, same STP writes, same checkpoints. Nothing in fleet mode alters what happens to an issue — only who runs it.

Fleet mode is ON when BOTH hold:

1. scope = sprint-wide;
2. the user answered the second question above with N executors. .agents/project.yaml → orchestration.max_workers is never itself a switch — it only caps how many of those N executors run per round once fleet mode is already on.

How the sessions get launched is then decided by the orchestration gate, and only that. Gate passes (binary present + runtime reachable) → the orchestration layer launches and supervises them. Gate fails → the same fan-out happens by hand: the conductor writes .session/sprint-testing/sprint-<N>/launch.txt (it writes it either way — one self-contained line per issue) and tells the user to open N terminals and paste one line each. The three-state gate itself lives in orca-orchestration/SKILL.md; this skill never reimplements it.

Silence rule. When the gate does not pass, the orchestration tool is never named, never recommended and never reported — not in the plan, not in the preflight gate, not in the ATR, not in the dashboard. A gap in tooling the user does not have is not a QA finding.

Worker mode is detected from the prompt, not from the environment. A worker's launch prompt opens with /sprint-testing <KEY> fleet worker … and names its brief; the token fleet worker plus the brief's Label / Task / Dispatch fields are the signal. Environment variables are NOT a reliable channel: measured on a real fleet, an env prefix written into a launch line did not survive every launcher and every worker ran with both variables empty (ADR-0006). They remain an optional redundant hint on the human-paste path only, and nothing in this skill depends on them. Canon: references/fleet-conductor.md §3.

Everything fleet mode adds — the conductor's duties, worker detection, brief seeding, launch.txt rules, rounds, the auth one-writer rule, browser isolation, claims, the liveness dashboard — is in references/fleet-conductor.md. The transport (sessions, terminals, mailbox, cleanup) is in orca-orchestration, cited from there as [ORCHESTRATION_TOOL] pseudocode. The conductor maneuver around it (boot with the Sprint Board, the watch pass, the round close, the resume after a reboot) is /sprint-conductor.

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 exposing every declared coverable type, 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

Where a Gotcha or a reference disagrees with §"TC creation timing" or §"Stage 1 Set-first order", those sections win.

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 (RTP), re-deriving the canonical title on the way in.
    -> 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
    -> CLOSE the artifacts Stage 1 opened (artifact-lifecycle.md §1):
         ATR  complete -> {{jira.status.test_execution.close}}   (after every run status is recorded)
         ATS  done     -> {{jira.status.test_set.close}}         (membership now final)
         ATP  complete -> {{jira.status.test_plan.completed}}    (results are in)
    -> File bugs via bug-report template when found
    -> Light stage verifier (artifact-lifecycle.md §5) closes the stage
    -> See references/reporting-templates.md

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

TC creation timing (modality-aware)

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.

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

Whenever this stage DOES create a Test work item, its summary MUST already match the canonical form {US_ID}: TC#: should <expected outcome> [<connector> <condition>] [given <precondition>] — {US_ID} = the Story key, # = a stable index within that Story, assigned once and never renumbered. A sprint-era title is not a draft to be tidied later: Stage 4 re-derives and verifies it on promotion (test-documentation/SKILL.md §"Title on promotion"), and a Test created outside the form forces a rename there. Full grammar + anti-patterns: references/acceptance-test-planning.md §TC nomenclature.

Which stage creates the TCs — {{TC_CREATION_STAGE}} (project knob)

The table above is the auto behavior, which is the shipped default. .agents/project.yaml → testing.tc_creation_stage (referenced as {{TC_CREATION_STAGE}}) lets a project override it. Resolve it at the modality gate (Session Start step 0), alongside {{TMS_CLI}}, and record the resolved value in test-session-memory.md next to the modality — it is sticky for the session, exactly like the modality.

Why the knob exists (maintainer's rationale): the two modalities pull in opposite directions and neither default is universally right. Under jira-native a Test issue IS documentation, so creating one per sprint outline fills the regression repository with cases that were never ROI-gated — noise that a later reader cannot distinguish from a curated regression case. Under jira-xray the Test is what Xray executes, and its whole traceability design (coverage panel, Test Execution runs, Test Plan membership) needs the item to exist during the sprint — deferring creation to Stage 4 costs the project its in-sprint evidence. So the default follows the tool (auto), and the knob exists because a project may legitimately weigh repository cleanliness against traceability differently.

On an unset / unrecognized value: treat it as auto and say so once. Do not ask the user mid-stage; a missing knob is the shipped default, not a gap.

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

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.

In worker mode the format is DECLARED, never asked. Nobody is watching a worker's terminal, and this is a real fork — Manual and Gherkin produce different artifacts, so it cannot be downgraded into report content the way a checkpoint can. So:

• the conductor asks the user ONCE per batch (per round, or once for the whole fleet run) and writes the answer into the ## Test-case format field of every brief it seeds;
• the worker reads the format from its brief and applies it to its whole batch, with no ask;
• if the brief is silent, the worker does NOT guess and does NOT prompt the user: it sends ONE ask to the conductor and waits (references/fleet-conductor.md §10). A guessed format costs a rewrite of every Test it created.

At N=1 this section is unchanged: the executor asks the user directly.

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

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)

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 (xray-cli/SKILL.md §Direction); 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.
5. Assignee = self on every artifact created here (ATP, ATS, ATR, every Test), set at create time — agentic-qa-core/references/artifact-lifecycle.md §2. Xray refuses membership edits on a Test Plan the caller does not own, so an unassigned ATP cannot have its test list updated later; the failure surfaces mid-flow, after the Plan already exists. A find-or-create that RETURNS someone else's artifact is not reassigned silently — ask the user first.

6. Statuses — the artifacts must LEAVE the status create dropped them in (artifact-lifecycle.md §1). At the END of Stage 1:

   Artifact	Born	Stage 1 leaves it at	Transition
   sprint Test (TC)	{{jira.status.test_case.draft}}	{{jira.status.test_case.ready}}	{{jira.transition.test_case.start_design}} then {{jira.transition.test_case.ready_to_run}}
   ATP	{{jira.status.test_plan.planning}}	{{jira.status.test_plan.ready}}	{{jira.transition.test_plan.designed}}
   ATS	{{jira.status.test_set.designing}}	stays designing — membership is not final until Stage 3	—
   ATR	{{jira.status.test_execution.active}}	stays active — the run has not happened yet	—
   STP (sprint altitude)	{{jira.status.test_plan.planning}}	{{jira.status.test_plan.ready}} once the sprint scope is set	{{jira.transition.test_plan.designed}}

   Each sprint Test is parented to the QA Test Repository epic (qa.qa_epics.test_repository_epic) — never the product Epic, never unparented (.agents/instructions/agent-local-context-pbi.md). A TC left at draft and unparented is the exact defect this rule exists to kill.

7. On an unmapped slug: run the fallback protocol in agentic-qa-core/references/artifact-lifecycle.md §4 — list the LIVE transitions, propose the closest synonym in ONE AskUserQuestion, fire the live id on yes, recommend bun run jira:sync-workflows. Never skip a transition silently.

TC∈ATS membership is ALWAYS a TC→ATS issue link (test slug), in this modality and in jira-native alike; here the Xray-internal membership (GraphQL) is written as well, never instead. TC∈ATP / TC∈ATR membership stays Xray-internal. An instance WITHOUT the Test Set work type has no ATS — fall back to direct TC→Story links. Canon: agentic-qa-core/references/traceability-linking.md §9.

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.

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.

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 <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).
2. Check .session/sprint-testing/<scope>/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/<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:

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 three-step probe here (testing.tms_cli in .agents/project.yaml -> Xray API evidence through /xray-cli, work types alone never decide -> ask the user). Persist the result into test-session-memory.md. In the same breath, resolve {{TC_CREATION_STAGE}} from .agents/project.yaml → testing.tc_creation_stage (unset / unrecognized → auto) and persist it next to the modality: it decides whether Stage 1 creates Test work items at all (§"Which stage creates the TCs"). Both values are sticky for the session and are NOT re-resolved mid-stage. 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). The STR carries testPlan → STP AND testPlan → RTP (dual membership). Regression runs DURING the sprint are RTRs (RTR: {scope-id}: Regression Testing, one per verdict) and belong to /regression-testing: never write one into the STR.
   • 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.

1. 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.
2. Extracts Team Discussion from the synced comments.md (decisions, tech notes, edge cases, blockers). Non-blocking.
3. Loads the project-wide context: the business context maps per touched level (bun run context:map business-data-context / business-api-context / business-e2e-context, --section <id> when one entity, endpoint group or journey is enough) and .context/PBI/qa-artifacts/master-test-plan.md.
4. 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; a fleet worker stages it under ## Module Learnings (candidate) in its test-session-memory.md instead and the conductor publishes it, references/session-entry-points.md), then re-syncs — the local file is Jira-synced, never authored by hand (see references/session-entry-points.md Step 4).
5. Explores backend ({{BACKEND_REPO}}) + frontend ({{FRONTEND_REPO}}) code.
6. Finds test data candidates via [DB_TOOL] on {{DB_MCP}}.

7. 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/instructions/agent-local-context-pbi.md), 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.

8. 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).
9. Writes a Story Explanation and STOPS for user confirmation. Do not proceed until the user OK's.
10. 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 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 the three-edge check (agentic-qa-core/references/traceability-linking.md §Traceability verification: Link List on Story + ATP + ATR, or bun xray trace {TICKET}).
• 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 on observation in the precondition's environment, else NOT RUN through the blocking ladder (agentic-qa-core/references/discovery-driven-doctrine.md §5) -> 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.
• N>1 executors (fleet mode): everything above still holds — the loop is the same queue, the waves are the same, the STP parity is the same, and the sprint-altitude writes stay with this session. What changes is that the per-issue 4-dispatch sequence runs inside a launched worker session instead of here, in rounds of at most orchestration.max_workers issues inside the current wave. Read references/fleet-conductor.md before seeding the first brief; the transport is [ORCHESTRATION_TOOL] pseudocode resolved in orca-orchestration.

Gotchas — inline rules you must apply every invocation

1. Credentials: always from .env. Never hardcode. Never guess passwords.
2. 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.
3. 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.
4. 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).
5. 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.
6. Story TCs are PLANNED in Stage 1 and executed in Stage 2 ("planning first"). Three exceptions, all intended: the bug repro Test created at fix-verification time (Gotcha 3); an exploratory probe that found a defect or is worth repeating, which becomes a Test in Stage 2 (§"TC creation timing"); and jira-native, which creates no Test work items in-sprint at all. Which stage creates them is §"TC creation timing (modality-aware)" and {{TC_CREATION_STAGE}}, never this gotcha.
7. Explain the story -> WAIT for OK. Never auto-proceed past Session Start without user confirmation. Same for bug triage — present the decision and wait.
8. Evidence directory: never repoint the shared .playwright/cli.config.json outputDir — it stays at the tool-owned directory it ships with (agentic-qa-core/references/evidence-conventions.md §1 Bucket A + §5). Every [AUTOMATION_TOOL] capture instead carries an explicit destination path resolving to .context/PBI/epics/EPIC-<KEY>-<slug>/stories/STORY-<KEY>-<slug>/evidence/, which is mandatory anyway because outputDir does not apply to .png.
9. Traceability check after Stage 1 (Modality jira-xray): run the three-edge check (agentic-qa-core/references/traceability-linking.md §Traceability verification: Link List on Story + ATP + ATR, or bun xray 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 (one TC→ATS test link per TC plus the Xray-internal membership, agentic-qa-core/references/traceability-linking.md §9). 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.
10. 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".
11. 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.
12. Language: all artifacts, TMS content, and commit messages in English. Mirror the user's language only in conversation.
13. 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.
14. 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.
15. 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.
16. 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. Lessons noticed during the session are PROPOSED to .session/<skill-slug>/<scope>/refinements.md and never applied to a live skill, per ../agentic-qa-core/references/skill-refinement-protocol.md; the footer's Refinements proposed: line counts them.

Cross-skill handoff — what this skill does NOT do

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

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 (the only browser path) | 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 | | [ORCHESTRATION_TOOL] | the multi-session orchestration layer — used ONLY in fleet mode (sprint-wide, N>1 executors) | orca-orchestration (the tool owner; this skill names verbs, never commands) |

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.

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) item in Modality jira-xray workflows. It is step 2 of the Set-first order, born from the {{jira.acceptance_test_plan}} field; without it the three-edge check fails (ATP→Story missing). The order is ATS first, ATP second, never ATP first (§"Stage 1 Set-first order"). The one exception is qa.methodology.gate_mode: light, which may collapse the ATP item as a declared, per-sprint collapse written in the STP with its debt item.
• 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 TMS modality (testing.tms_cli in .agents/project.yaml) 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, and NEVER assume [ISSUE_TRACKER_TOOL] converts Markdown for you. There is no implicit conversion on the CLI path: a Markdown body handed to it is stored verbatim, so the field renders literal # and ** (measured on a real fleet run; see ADR-0006). The real path is explicit, in three steps: author the body as Markdown → convert + validate it with the bundled converter .agents/skills/acli/scripts/md-to-adf.ts → publish the resulting ADF JSON through the matching surface (body-file / JSON-payload / REST field update). Mechanics: agentic-qa-core/references/acli-integration.md and .agents/skills/acli/references/adf-authoring-style.md §5; the two failure modes it can still hit: agentic-qa-core/references/jira-publishing-gotchas.md. A plain-text comment needs no conversion — only rich-text fields do.
• 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/instructions/agent-ticket-work.md — 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.
• S18. NEVER leave an artifact in the status Jira's create transition dropped it in. An ATP frozen at {{jira.status.test_plan.planning}}, an ATS at {{jira.status.test_set.designing}}, an ATR at {{jira.status.test_execution.active}} or a TC at {{jira.status.test_case.draft}} after the stage that owns it closed is a reported defect of this harness, not a cosmetic detail — it tells the team the work never happened. Fire the transition, or run the agentic-qa-core/references/artifact-lifecycle.md §4 fallback and ask. A silent skip is never an option.
• S19. NEVER create a Test Plan, Test Execution, Test Set or Test without an assignee. Xray refuses membership edits on a Plan the caller does not own, so an unassigned ATP becomes a blocker the moment its test list must change (agentic-qa-core/references/artifact-lifecycle.md §2). A find-or-create that returns someone ELSE's artifact is never reassigned silently — ask first.

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: executors ASKED and answered (1 or N). N>1 → references/fleet-conductor.md read and its checklist run; N=1 → nothing about fleet mode applies and nothing about it was said to the user
• 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 the three-edge check (Story↔ATS coverage + ATP↔Story + ATR↔Story administrative + lists match — agentic-qa-core/references/traceability-linking.md §Traceability verification) — 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 1 statuses left correct: TCs at {{jira.status.test_case.ready}} (parented to QA Test Repository), ATP at {{jira.status.test_plan.ready}}, ATS still designing, ATR still active — and every one of them has assignee = self (S18 / S19)
• 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
• Story approved: {{jira.quality_token_usage}} written from measured consumption, or N/A stated with the reason (sprint-orchestration.md Stage 3 step 5b)
• Stage 3 closed the Stage-1 artifacts: ATR → {{jira.status.test_execution.close}} · ATS → {{jira.status.test_set.close}} · ATP → {{jira.status.test_plan.completed}} (or each one's unmapped slug went through the artifact-lifecycle.md §4 fallback and was ASKED, never silently skipped)
• Light stage verifier run at the close of each stage per agentic-qa-core/references/artifact-lifecycle.md §5 — every line YES or a stated N/A
• 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)