| name | sprint-testing |
| description | Orchestrates in-sprint manual QA per ticket across Stages 1 (Planning), 2 (Execution) and 3 (Reporting). Use for user-story testing, bug retesting, and batch-sprint 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, next ticket in sprint, generate the SPRINT-N-TESTING framework, 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). |
| license | MIT |
| compatibility | ["claude-code","copilot","cursor","codex","opencode"] |
| complementary_categories | ["testing-e2e","testing-api","issue-tracker"] |
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:
.claude/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 ticket at a time (single-ticket), or N tickets managed by a framework file (batch-sprint).
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, ./dispatch-patterns.md, ./orchestration-doctrine.md, ./session-management.md, ./preflight-gate.md, ./adr-doctrine.md — cited inline by the sections that use them.
Compact Rules
Test-design doctrine (binding — full canon: agentic-qa-core/references/test-design-doctrine.md):
- AC-pass is the FLOOR, not the goal. Coverage = AC-conformance + risk-beyond-AC (boundaries, errors, states, anomalies). Never report "% of ACs verified" as completeness.
- 1:N is the default: explode every non-trivial AC into multiple cases (EP partitions + boundaries + states + contexts). Collapsing an AC to one case requires a written "trivially atomic" justification.
- Apply techniques by trigger: EP always; BVA wherever a range / limit / length / date-window exists; State-Transition for stateful entities; Decision Table when 2+ conditions interact; Pairwise when 3+ combinable factors (log the reduction); Error-Guessing charters for experience-based risk.
- A criterion is a business assertion; a test case is a concrete exploration of it. Run the Test-Design Checklist before finalizing the ATP.
Defect-management doctrine (binding — full canon: agentic-qa-core/references/defect-management-doctrine.md):
- CLASSIFY before filing — stop hardcoding "Bug". Bug = affected feature already live above Staging (end-user visible); Defect = feature still pre-release (Staging or below), the normal output of sprint testing; Improvement = not a broken AC (an enhancement, or an under-specified/absent AC surfaced by a test-beyond-AC). Classification follows the FEATURE's lifecycle stage, not where the problem was found (Part 1).
qa_assignee ({{jira.qa_assignee}}) = the authenticated session user (self-assign). Set it when a Story is TAKEN INTO TESTING (start_testing) and on every filed Bug / Defect / Improvement. NEVER-OVERWRITE an existing owner (read-before-write); distinct from the native dev assignee (Part 2).components (native, MANDATORY) = the affected product module/Epic, must pre-exist in the Jira Components module (Part 3).- Three-axis model: parent = QA Defect Management process epic (
qa.qa_epics.defect_epic, found-or-created — NEVER a product/dev epic, NEVER the Story); issue link = the source Story (traceability); components = product module (Part 4).
priority (native) is auto-derived from {{jira.severity}} (critica→Highest, mayor→High, moderada→Medium, menor→Low, trivial→Lowest); override with a 1-line justification (Part 5.1).
Sprint-testing operational rules:
- Three stages, always in order: Stage 1 Planning → Stage 2 Execution → Stage 3 Reporting. Hand off Stages 4/5/6 to
test-documentation / test-automation / regression-testing.
- Jira is source of truth. Read tickets via
bun run jira:sync-issues get <KEY> --include-comments, then the synced .md. NEVER acli workitem view for custom fields (returns null).
- Bugs run the veto + triage + risk-score decision tree BEFORE any ATP is written.
- Execution = smoke pass first, then trifuerza (UI/API/DB) exploration; capture evidence under the PBI folder.
- API testing = three-tool maneuver: OpenAPI MCP for schema (READ-ONLY) →
bun run api:login for the token (→ .auth/tokens.env) → curl for authenticated requests. NEVER execute via the OpenAPI MCP. Canon: agentic-qa-core/references/api-testing-doctrine.md.
- Consult
domain-glossary.md (if present) before authoring the ATP, refined ACs, and TC outlines.
- On any subagent failure: STOP, report partial state, offer retry / skip-stage / abort. No auto-fix, no auto-rollback.
Read full SKILL.md when: starting a sprint cold, resuming a session, or handling a bug-triage / batch-sprint flow not covered by the rules above.
Inputs — read these first, in this order
Canonical reading order for any AI starting cold on a sprint-testing workflow. Read in order; stop earlier when the ticket is small enough that later inputs add no signal.
.agents/project.yaml — project identity, env URLs, {{PROJECT_KEY}}, MCP names, active environment..agents/jira-required.yaml — canonical slug catalog (custom fields, statuses, transitions) for the active workspace..agents/jira-fields.json — slug → numeric custom-field-ID mapping for {{jira.<slug>}} resolution at runtime..agents/jira-workflows.json — workflow + transition catalog (resolves Ready For QA → In Testing → Tested for Story / Bug / Test Case work types)..context/PBI/epics/EPIC-<KEY>-<slug>/stories/STORY-<KEY>-<slug>/context.md — ticket-local context: session notes, open questions (hand-authored; read if it already exists from a prior Session Start). NON-Jira file — never a Jira mirror..context/master-test-plan.md — regression Epic pointer, modality decision (Xray vs Jira-native), what to test and why..context/business/business-feature-map.md — feature catalog vocabulary; resolves "what epic owns this story" for the epics/EPIC-<KEY>-<slug>/ PBI folder naming (module = Epic, 1:1)..context/business/domain-glossary.md (if present) — canonical domain vocabulary; consult BEFORE authoring the ATP, refined ACs, and TC outlines so test names, entity terms, and Gherkin wording use canonical terms and avoid anti-glossary banned terms. If a new or ambiguous term surfaces during testing, flag it in the Stage 3 QA comment for the PM to add via the glossary's change protocol — NEVER edit the glossary from a testing session.- The Story or Bug ticket itself — AC, ATP, comments — read via
bun run jira:sync-issues get <KEY> --include-comments, then read the synced .md files (story.md, acceptance-criteria.md, acceptance-test-plan.md, comments.md) under the STORY folder. Jira is source-of-truth; the synced .md is a read-only cache. NEVER acli workitem view for custom fields — it returns null.
.env — LOCAL_USER_* / STAGING_USER_* credentials. NEVER hardcode; always read at runtime.kata-manifest.json — registry of existing KATA Components + ATCs. Check before proposing new ATCs in Stage 3 hand-off so the test-automation phase doesn't duplicate work.
Optional inputs. master-test-plan.md, the business maps, and domain-glossary.md frequently arrive after /project-discovery runs and may be absent — proceed without them and surface a missing_input note in the Stage 1 ATP so a later pass can fill the gap. kata-manifest.json is only load-bearing at the Stage 3 → test-automation hand-off; skip in pure manual-QA invocations.
Subagent Dispatch Strategy
Orchestration & Session contracts: this skill follows ./orchestration-doctrine.md (mandatory subagent dispatch — main thread is command center) AND ./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 ./stage-gates.md: verify a stage's DoD (planning stages include the Test-Design Checklist) BEFORE recording its progress checkpoint and advancing.
This skill scopes per ticket. Single-ticket mode: <scope> = <JIRA-KEY> (e.g. UPEX-123). Batch-sprint mode: <scope> = sprint-<N>/<JIRA-KEY> (one nested directory per ticket in the wave). Session state lives at .session/sprint-testing/<scope>/{plan.md, progress.md} per agentic-qa-core/references/session-management.md §3 + §9. The per-ticket test-session-memory.md is a SEPARATE concern: it carries TMS modality + ticket context + stage state shared across the 4 sub-agent dispatches (domain memory). Both files coexist — plan.md indexes the session; test-session-memory.md holds the cross-stage shared payload.
This skill is compliant with the doctrine in CLAUDE.md §"Orchestration Mode (Subagent Strategy)" and the session contract in .claude/skills/agentic-qa-core/references/session-management.md. Every dispatch follows the 6-component briefing format defined in .claude/skills/agentic-qa-core/references/briefing-template.md, and the pattern selected per stage matches the decision guide in .claude/skills/agentic-qa-core/references/dispatch-patterns.md. This skill operates in two modes (single-ticket and batch-sprint) and BOTH modes use the same four dispatch points per ticket — Session Start -> Stage 1 -> Stage 2 -> Stage 3. The only difference is that batch mode loops them once per ticket. The full briefings (Goal / Context docs / 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-ticket) | Single | dispatch a session-start subagent: fetch ticket from issue tracker, load .context/, create the PBI folder + context.md + test-session-memory.md, return ticket 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-ticket mode runs ONE pass through these four dispatches. Batch mode loops them per ticket. There is no longer a "single-ticket 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 ticket 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 .claude/skills/agentic-qa-core/references/orchestration-doctrine.md.
Scope — pick the mode first
| Mode | Input | Output | Use when |
|---|
| Single ticket — User Story | One story ID (e.g. {{PROJECT_KEY}}-123) | ATP + ATR + QA comment + ticket 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 Tests this sprint, promoted to regression in Stage 4 (see "TC creation timing") | Full QA on one story end to end |
| Single ticket — Bug | One bug ID | Triage decision, then either Code-Review-only OR ATP + ATR + verification report | Retesting a bug fix on staging |
| Batch sprint | SPRINT-{N}-TESTING.md framework file | Per-ticket artifacts + updated framework file + session summary | Processing a whole sprint backlog, with interruption + resume support |
Rules for picking:
- Story ID with status Ready-for-QA -> Single ticket / User Story.
- Bug ID deployed to staging -> Single ticket / Bug.
- Sprint number, "process sprint X", or an existing
SPRINT-{N}-TESTING.md -> Batch sprint.
- If the framework file does not exist yet, generate it first (see
sprint-orchestration.md).
Workflow — one pipeline for all modes
Session Start (always first)
-> PBI folder + context.md + 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 -> CREATE + EXECUTE `Test` issues for the planned outlines at executable
detail, run via a Test Execution (Xray plugin design). Stage 4 promotes
the regression-worthy ones into the Regression Test Plan.
-> For Bug: veto check + Bug Analysis + ATP/ATR (no TCs in-sprint — the bug IS the immediate
retest case). If regression-worthy, Stage 4 ensures a persistent Test covers it —
REUSE the existing failed Test or CREATE one (golden rule; both modalities).
-> See references/acceptance-test-planning.md and references/feature-test-planning.md
-> TC work-item timing rule -> see "TC creation timing (modality-aware)" below
Stage 2 — Execution
-> Smoke test is always first (Go / No-Go)
-> Then UI / API / DB exploration per what changed
-> Evidence into .context/PBI/epics/EPIC-<KEY>-<slug>/stories/STORY-<KEY>-<slug>/evidence/
-> See references/exploration-patterns.md
Stage 3 — Reporting
-> Fill ATR, post QA comment, transition ticket
-> File bugs via bug-report template when found
-> See references/reporting-templates.md
---> Hand off (cross-skill, NOT this skill):
Stage 4 -> test-documentation
Stage 5 -> test-automation
### TC creation timing (modality-aware) — AUTHORITATIVE
> Resolves the one question that decides this skill's whole shape: *when does a test case become a work item in the TMS?* Guiding principle: **a test is persisted into the REGRESSION repository because it will be re-executed (manual or automated), never to hit a count.** The mechanism differs by modality because the TMS tools differ — an Xray `Test` issue is an **execution unit**, a Jira-native `Test` issue is **documentation**.
**Key distinction:** an **execution artifact** (how you run + record a test this sprint) is NOT the **regression repository** (the curated set of repeatable tests). The principle governs the repository, not the sprint execution artifacts.
| | **Modality jira-native** | **Modality jira-xray** (`bun xray` CLI) |
|---|---|---|
| Stage 1 (Planning) | TC **outlines only** (names + 1-line precond/expected in the ATP). **No `Test` work items** — a native `Test` issue IS documentation, so it waits for the Stage-4 regression-worthy gate. | **ASK the format once per batch** (see "Test-case format — ask once per batch" below), then **create + execute** Xray `Test` issues for the **planned outlines**, at *executable* detail (preconditions + runnable steps), and run them via a **Test Execution** — all in one pass. By Xray's plugin design the `Test` is the execution unit, so generating these artifacts is what makes the rest of the Xray flow work. **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 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-ticket mode runs the same 4 dispatches as batch mode: 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 ticket. Batch mode loops these same four dispatches through Wave 1 PENDING tickets in the framework file and updates the framework file after each ticket.
Readiness Preflight Gate (MANDATORY — runs before Phase 0)
Full doctrine: agentic-qa-core/references/preflight-gate.md. Runs FIRST, before the resume check. Two laws: (1) args-as-answers — "QA UPEX-123 on staging" already answers env + scope; "test the login API" already answers the surface (API). Ask only the gaps. (2) probe, don't assume — a configured MCP is RED until it actually answers. Surface gaps + REDs as ONE AskUserQuestion checklist; self-fix with approval + explanation; STOP on any blocking RED. This is the heaviest gate in the repo because Stage 2 exercises UI + API + DB live. Generic baseline (env resolution, test-user creds, secret/restart handling, the two laws, output contract) is inherited from the reference §3.1 — not repeated here. Below is only this skill's specific capability delta.
| Capability | Need | Why here |
|---|
| Framework adapted (artifacts present) | REQUIRED | Live QA needs the project wired — {{WEB_URL}} / MCP names are null on a generic boilerplate. Probe the reference §4 ADAPTED signals; still generic → STOP and tell the user to run /project-discovery → /adapt-framework themselves. The gate NEVER auto-runs them. |
| Active env reachable | REQUIRED | Authoring an ATP against a dead env is the highest-cost waste. Probe {{WEB_URL}} + {{API_URL}} root. This subsumes the env half of Session Start §0.6 — pulled to t=0. |
| Test-user credentials + roles | REQUIRED | <<ACTIVE_ENV>> creds in .env. Ask how many roles the ticket needs; one token per role via scripts/api-login.ts. |
Issue-tracker ([ISSUE_TRACKER_TOOL]) + TMS modality | REQUIRED | All ATP/ATR/QA-comment/transition writes go to Jira. Load /acli; resolve modality; load /xray-cli + XRAY_* if jira-xray. |
| OpenAPI MCP (schema read-only) | SCOPE — when API surface is in scope | The openapi MCP is schema-read-only — discover endpoints + read schemas (list-api-endpoints / get-api-endpoint-schema); it does NOT execute authenticated requests. Probe that a schema call returns the spec. Generic/unset spec → /adapt-framework. Execution is curl's job (next row). |
API token for curl (bun run api:login) | SCOPE — when API execution is in scope | Authenticated requests run via curl, not the MCP. Mint: bun run api:login [<env>] [--role <role>] → .auth/tokens.env. Execute: source .auth/tokens.env && curl -H "Authorization: Bearer $API_TOKEN_<ROLE>_<ENV>" "$API_BASE_URL/<path>". No restart needed (the token never enters an MCP). Canon: agentic-qa-core/references/api-testing-doctrine.md. |
| DBHub MCP | SCOPE — when DB validation is in scope | The trifuerza DB leg. Probe dbhub lists schema/tables; DBHUB_* in .env. Unset → user fills .env + RESTART (spawn-time). |
Playwright / /playwright-cli | SCOPE — when UI surface is in scope | Smoke + UI exploration. Browser present (bun run pw:install if not). |
Email (resend) — can RECEIVE | SCOPE — magic-link / auth-token tickets only | Subsumes the inbox half of Session Start §0.6. A send-only provider cannot complete a magic-link flow → STOP before Stage 1. |
kata-manifest.json | OPTIONAL | Only load-bearing at the Stage 3 → /test-automation handoff (anti-duplication). |
Surfaces (UI / API / DB / code-review-only) are decided by Stage 1 Planning's triage + veto + risk-scoring — NEVER asked of the user (reference §5). The gate only probes and reports which surface tools are ready; Stage 1 reads that report and picks the trifuerza subset on its own. A scope-conditional tool stays REQUIRED only once Stage 1 selects its surface — if RED then, surface the remedy at that point. Session Start §0.6 stays as written — this gate is its t=0 generalization, not a replacement. After the gate clears (generic baseline + any already-evident surface tools GREEN), continue to Phase 0 below.
Phase 0 — Session resume check (MANDATORY, inline)
Before Session Start dispatch, run the resume contract from agentic-qa-core/references/session-management.md §4:
- Compute prospective
<scope> from invocation: <JIRA-KEY> (single-ticket) or sprint-<N>/<JIRA-KEY> (batch — once per ticket in the wave loop).
- Check
.session/sprint-testing/<scope>/progress.md.
- If it does NOT exist → proceed to Session Start (writes
plan.md).
- If it DOES exist:
- Read
plan.md + tail of progress.md.
- Optionally read
.context/PBI/epics/EPIC-<KEY>-<slug>/stories/STORY-<KEY>-<slug>/test-session-memory.md for the per-ticket domain state (load-bearing across the 4 sub-agent dispatches).
- Surface to the user: last completed stage (Session Start / Stage 1 / Stage 2 / Stage 3) + next stage + 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.
Batch-sprint mode: Phase 0 fires once per ticket as the loop enters it (NOT once at sprint-loop entry). Per-ticket resume keeps batch progress fine-grained.
Session Start — the universal entry
Every invocation starts by initializing the session, even in batch mode. Session Start:
- Resolve TMS modality (Xray on Jira vs Jira-native). By excellence ATP/ATR are real Jira items — a
Test Plan issue (ATP: {STORY-KEY}: {story title}) parented to the QA Master Test Plan epic, and a Test Execution issue (ATR: {STORY-KEY}: Story Testing) parented to the QA Test Artifacts epic; the Story custom-field + comment mirror (Modality jira-native) is a fallback ONLY when those work types are unavailable. The modality probe decides which path is live. Title grammar + epic parenting + the Feature-altitude FTP/FTR names: references/acceptance-test-planning.md. Full resolution algorithm lives in test-documentation/SKILL.md §Phase 0 — apply the same four-step probe here (CLAUDE.md -> master-test-plan.md -> list issue types -> ask the user). Persist the result into test-session-memory.md.
0.1. Load required tool skills — based on the TMS modality resolved in Step 0:
- Always load
/acli (Jira WRITE operations: comment, transition, link, custom-field update, bug creation). Detailed READS (ACs, ATP/ATR, description, comments) do NOT use /acli — they use bun run jira:sync-issues get <KEY> --include-comments then read the synced .md. See agentic-qa-core/references/acli-integration.md §"Reads vs writes".
- In Modality jira-xray: also load
/xray-cli for Test / Test Execution / Test Plan / Test Run operations and traceability reads.
- In Modality jira-native:
/acli covers [ISSUE_TRACKER_TOOL] writes and [TMS_TOOL] operations — no additional skill needed. Detailed reads still route through the sync script.
This step is mandatory before any pseudocode block below executes. The skills carry the concrete syntax, flags, and JSON payloads this skill intentionally omits.
0.5. Sprint roadmap checkpoint (batch-sprint mode only — skip in single-ticket mode):
- Detect batch mode from the user invocation ("process sprint N", "continue sprint", a
sprint-file parameter, or any phrase that implies a sprint loop).
- Check whether
.context/reports/SPRINT-{N}-TESTING.md exists for the target sprint.
- Missing -> generate it before entering the ticket loop. Delegate to
sprint-orchestration.md §Part 1 — Sprint Roadmap Generator.
- Present but older than 24h, OR the user explicitly asks for a refresh -> regenerate (warn + confirm overwrite).
- Present and fresh -> proceed.
- Single-ticket and bug-only invocations skip this step entirely — they do not need a roadmap file.
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.
- Fetches the ticket via
bun run jira:sync-issues get <KEY> --include-comments (title, ACs, priority, comments), then reads the synced .md files under the STORY folder. NEVER acli workitem view for custom fields.
- Extracts Team Discussion from the synced
comments.md (decisions, tech notes, edge cases, blockers). Non-blocking.
- Loads the project-wide context files:
.context/business/business-data-map.md, .context/business/business-feature-map.md, .context/business/business-api-map.md, .context/master-test-plan.md.
- Loads or creates
module-context.md (3-level hierarchy: project -> module -> ticket).
- Explores backend (
{{BACKEND_REPO}}) + frontend ({{FRONTEND_REPO}}) code.
- Finds test data candidates via
[DB_TOOL] on {{DB_MCP}}.
- Creates the PBI folder and files:
.context/PBI/epics/EPIC-<KEY>-<slug>/stories/STORY-{{PROJECT_KEY}}-{number}-{brief-title}/
context.md # hand-authored: session notes + open questions (NON-Jira)
test-session-memory.md # hand-authored: shared memory across the 4 sub-agent dispatches (NON-Jira)
evidence/ # screenshots, gitignored
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.
- Writes the session
plan.md at .session/sprint-testing/<scope>/plan.md per agentic-qa-core/references/session-management.md §6 — Goal (one sentence per ticket), Inputs (PBI paths + TMS modality + Team Discussion summary), Approach (mode + per-stage dispatch pattern), Phase breakdown (Session Start / Stage 1 / Stage 2 / Stage 3 with dispatch pointer + exit condition), Risks (from triage), Verification checklist, Cross-references (cites context.md, test-session-memory.md, acceptance-test-plan.md, acceptance-test-results.md).
- Writes a Story Explanation and STOPS for user confirmation. Do not proceed until the user OK's.
- After OK, appends the first progress entry
## Session Start — <ts> with status: completed, next: Stage 1 — Planning to .session/sprint-testing/<scope>/progress.md.
Details, templates and error table live in references/session-entry-points.md.
Mode branches — what changes after Session Start
Both single-ticket and batch modes run the SAME 4-dispatch cadence (Session Start -> Stage 1 -> Stage 2 -> Stage 3) per ticket. Use the briefings in references/sprint-orchestration.md §"Sub-agent prompt templates" verbatim — do NOT inline a stage just because there is only one ticket. The previous "single-ticket inline" path is REMOVED. The notes below describe only what is different per ticket type or per mode (TMS payload shape, framework-file update timing, etc.). The dispatch sequence itself is invariant.
Single-ticket, 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): link the Story only to its ATP and ATR ("is tested by"); link each created TC to the ATP (designed-by) and the ATR (executed-by) — do NOT link TCs directly to the Story (see Gotcha #9). Verify with [TMS_TOOL] trace.
- Stage 2: Smoke test -> UI / API / DB exploration beyond the planned outlines -> update outline status (native) or Test runs in the Test Execution (xray) PASSED / FAILED -> fold any newly-discovered partition/boundary/transition back into the outline set; an exploratory probe becomes a
Test only if it found a defect or is worth repeating -> file bugs if any.
- Stage 3: Author ATR Test Report -> apply the modality branch (reporting-templates.md §2.3-2.4): Modality jira-native -> write the
{{jira.acceptance_test_results}} field (or ## Acceptance Test Results (ATR) fallback comment) then jira:sync-issues get <KEY> --include-comments -> acceptance-test-results.md in the STORY folder; Modality jira-xray -> update the Test Execution then jira:sync-issues get <ATR_KEY> -> .context/PBI/test-executions/TESTEXEC-<ATR_KEY>-<slug>.md -> 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-ticket, 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, no TCs in-sprint (the bug is the immediate retest case). Fill Bug Analysis inside the ATP. 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 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.
Batch sprint
- Pre-step: generate
SPRINT-{N}-TESTING.md from the sprint backlog if it does not exist (see sprint-orchestration.md).
- Loop: read Wave 1 for the first
PENDING ticket, dispatch the same 4-stage sequence per ticket, after each ticket update the framework file + present a per-ticket summary + wait for user OK.
- Interrupted session resume: on loop entry per ticket, Phase 0 reads
.session/sprint-testing/sprint-<N>/<TICKET>/progress.md (canonical resume signal per agentic-qa-core/references/session-management.md §4). Domain state for an in-flight ticket is in .context/PBI/epics/EPIC-<KEY>-<slug>/stories/STORY-<KEY>-<slug>/test-session-memory.md (load-bearing for the 4 sub-agent dispatches). The two files serve different concerns: progress.md decides "which stage is next?"; test-session-memory.md carries the per-ticket payload that each sub-agent reads. Both are checked.
- After each stage subagent returns, the orchestrator appends a phase entry to
progress.md per agentic-qa-core/references/session-management.md §7. After Stage 3 completes, the orchestrator runs Archive: moves .session/sprint-testing/<scope>/ to .session/.archive/<YYYY-MM-DD>-sprint-testing-<scope>/ and calls mem_session_summary. The PBI artifacts under .context/PBI/ and the framework file SPRINT-{N}-TESTING.md stay in place — those are the canonical deliverables.
- Stop on TOOL FAILURE. Pause on BUG_FOUND. Update framework file ONLY after Stage 3 completes.
Gotchas — inline rules you must apply every invocation
- Credentials: always from
.env. Never hardcode. Never guess passwords.
- PBI folder naming: canonical layout is
.context/PBI/epics/EPIC-<KEY>-<slug>/stories/STORY-<KEY>-<slug>/ (module = Epic, 1:1). <slug> is max 5 words, kebab-case, AI-generated from the ticket title. Epic-level files live in the EPIC folder; story-level files in the STORY folder.
- Bugs get ATP + ATR, no TCs in-sprint. The bug ticket is the implicit immediate test case; reproduction steps = test steps. But a regression-worthy bug MUST end with a persistent Test in Stage 4 — reuse the existing failed Test or create one (golden rule). Not every bug qualifies.
- Smoke test is mandatory as the first action in Stage 2. If smoke fails (No-Go), stop and report — do not proceed to deep exploration. Smoke failure is an env-level blocker and always stops; deep-exploration findings follow the graduated rule in #10 (a FAIL mid-pass is not auto-Critical).
- Bug veto table — SKIP retesting when the bug is pure text / CSS / docs / config / tech-debt cleanup with no functional change. REQUIRE retesting regardless of score when it touches money, data integrity, auth, external integrations, state machines, or calculations. Veto beats risk score.
- TCs are created in Stage 1, NEVER in Stage 2. Stage 2 executes what Planning produced; new TCs found during exploration are added via
[TMS_TOOL] tc create but the rule is "planning first".
- Explain the story -> WAIT for OK. Never auto-proceed past Session Start without user confirmation. Same for bug triage — present the decision and wait.
- Evidence directory: always configure
.playwright/cli.config.json outputDir to .context/PBI/epics/EPIC-<KEY>-<slug>/stories/STORY-<KEY>-<slug>/evidence/ BEFORE using [AUTOMATION_TOOL]. Screenshots need the full path in --filename because outputDir does not apply to .png.
- Traceability check after Stage 1 (Modality jira-xray): run
[TMS_TOOL] trace {TICKET} and verify the model — the Story is linked ONLY to its ATP (Test Plan) and ATR (Test Execution) as "is tested by". Individual TCs are NOT linked directly to the Story (avoids noise); they aggregate via ATP/ATR — the ATP "designs" the TCs (TC "is designed by" ATP) and the ATR "executes" the TCs (TC "is executed by" ATR). So verify: Story↔ATP, Story↔ATR, each TC↔ATP (designed-by), each TC↔ATR (executed-by) — NOT TC↔Story. Full doctrine: test-documentation/references/traceability-linking.md + tms-architecture.md. Bugs: traceability "gaps" for missing TCs are expected and OK.
- Graduated stop/pause protocol: TOOL FAILURE -> stop, report, await user. Blocking BUG_FOUND (smoke/env down, data integrity, security-exploitable) -> pause, present bug, await decision; NEVER dispatch the next sub-agent while unresolved. Non-blocking finding (cosmetic, minor validation, edge-case on a non-critical TC, framework-default pending recalibration) -> the Execution subagent logs it and CONTINUES the pass; the orchestrator surfaces it at Stage 2 close. A FAIL is not auto-Critical — triage first (severity per
references/reporting-templates.md §1.4; security/auth/framework-default recalibrated at §5.0). See references/exploration-patterns.md "Finding triage".
- Framework file update timing: only update
SPRINT-{N}-TESTING.md AFTER Stage 3 completes and the orchestrator-side checklist verifies. Not earlier.
- Language: all artifacts, TMS content, and commit messages in English. Mirror the user's language only in conversation.
- Environment + inbox preflight before ATP: Session Start §0.6 probes
{{WEB_URL}} / {{API_URL}} for reachability (and, for email/auth-dependent stories, that the inbox can receive) BEFORE any ATP/Jira write. A dead env or send-only inbox is caught here with a STOP, not at Stage 2 after the ATP is already authored. Reachability gate ≠ Stage 2 smoke — see S7.
- Severity recalibration before blocking a Story: a Story TC FAIL is NOT automatically a blocking defect. When the failing TC is security/auth/framework-default class (cookie flags, CSP/HSTS headers, SDK-by-design behavior), run the recalibration gate (
references/reporting-templates.md §5.0) BEFORE firing {{jira.transition.story.defect_reported}}/blocked: state the framework-default/mitigation hypothesis, cite one verification fact, surface to the user. A recalibrated finding becomes GO-with-debt (PASSED WITH ISSUES), not a blocker. Mechanical path stays the default for ordinary functional FAILs. Once the gate confirms a real blocking defect and the defect_reported → blocked transition fires, also create the Story is blocked by Bug issuelink via {{jira.link_types.blocks.name}} (the Bug blocks the Story) — methodology step in references/reporting-templates.md §5.1, mechanics in agentic-qa-core/references/traceability-linking.md (§2/§4/§6). The status transition alone does not record the dependency edge.
- Session env override: to test against an ad-hoc URL not in
.agents/project.yaml (broken staging, ephemeral preview deploy, hotfix branch URL), record it ONCE in test-session-memory.md §Environment as WEB_URL_OVERRIDE / API_URL_OVERRIDE. When set, it beats the project.yaml active-env value for every stage and is read automatically by all four dispatches — never re-thread it per briefing, and never write it to project.yaml (session-only). Distinct from active_env switching, which picks a named env from project.yaml.
- Session-footer contract (mandatory at close): the final stage is not done until the two chat-facing blocks from
../agentic-qa-core/references/session-footer-contract.md are printed: (1) consolidated screenshot list — repo-relative paths, verified on disk, bug annotations first — plus in-flow surfacing of every capture's path the instant it lands; (2) Session Footer listing skills/MCPs/CLIs actually used + testing levels touched, with explicit "none" entries for expected-but-untouched levels. Framing for this skill: execution. Multi-subagent sessions: each stage report carries the five footer fields (skills_loaded, mcps_used, clis_used, testing_levels_touched, screenshots_captured); the orchestrator compiles the footer ONCE at close. Chat only — never in a Jira comment or ATR body.
Cross-skill handoff — what this skill does NOT do
| Predecessor | Load this skill | Reason |
|---|
| Pre-sprint AC refinement on a batch of backlog Stories | shift-left-testing | Stage 0. If the Story passed through /shift-left-testing and carries label shift-left-reviewed with a dated label <30 days old, Stage 1 here short-circuits Phases 1-3 of acceptance-test-planning.md and continues from Phase 4. If the Story did NOT pass through Shift-Left, Stage 1 runs all phases in full — but this is more expensive in-sprint than pre-sprint. |
| After Stage 3 you need... | Load this skill | Reason |
|---|
| Formalize TCs in Jira/Xray, calculate ROI, decide Candidate / Manual / Deferred | test-documentation | Stage 4. This skill produces the inputs (outlines + execution evidence); test-documentation produces the formal regression backlog — creating Test work items (jira-native) or creating/promoting them into the Regression Test Plan (jira-xray), regression-worthy scenarios only. |
| Write the automated test code (KATA Page / Api + test file) | test-automation | Stage 5. Plan -> Code -> Review pipeline. |
| Run the regression or smoke suite in CI and emit a GO/NO-GO verdict | regression-testing | Stage 6. This skill's Stage 2 smoke is local-manual, not the CI suite. |
Generate business-data-map.md, business-feature-map.md, business-api-map.md, master-test-plan.md | project-discovery (or the individual /business-*-map and /master-test-plan commands) | Sprint-testing consumes these; it does not create them. |
If Session Start reports that any of the project-wide context files are missing, stop and hand off to project-discovery (or the relevant command). Do not continue without them.
Pseudocode tags used here
| Tag | Resolves to | Defined in |
|---|
[TMS_TOOL] | xray-cli skill, Atlassian MCP, or {{TMS_CLI}} | CLAUDE.md Tool Resolution |
[ISSUE_TRACKER_TOOL] | acli, Atlassian MCP, or {{ISSUE_TRACKER_CLI}} | CLAUDE.md Tool Resolution |
Reads vs writes split (per agentic-qa-core/references/acli-integration.md §"Reads vs writes"): detailed reads of an issue (custom fields, ACs, ATP/ATR, description, comments) use bun run jira:sync-issues get <KEY> --include-comments (or jql "<query>") then read the synced .md — NEVER acli workitem view (returns null for custom fields). Writes / transitions / links / bug creation / trivial summary-or-status lookups stay on [ISSUE_TRACKER_TOOL] (/acli). Traceability (link graph Story↔ATP↔ATR↔TC, Xray run status) stays on [TMS_TOOL] / /acli / /xray-cli — do NOT migrate trace reads to the sync.
| [AUTOMATION_TOOL] | playwright-cli skill or Playwright MCP | CLAUDE.md Tool Resolution |
| [DB_TOOL] | DBHub MCP or Supabase MCP | CLAUDE.md Tool Resolution |
| [API_TOOL] | Schema read → OpenAPI MCP (read-only); execute → curl (token via bun run api:login) | CLAUDE.md Tool Resolution + agentic-qa-core/references/api-testing-doctrine.md |
Concrete tools (bun, git, gh) are used literally. Project variables like {{PROJECT_KEY}}, {{DB_MCP}}, {{WEB_URL}} are resolved from .agents/project.yaml (env-scoped vars resolve to the active environment).
References — read the narrow one for the situation
All references are self-contained. Load one at a time.
| Reference | Read when |
|---|
sprint-orchestration.md | Running batch-sprint mode, generating the SPRINT-{N}-TESTING.md framework file, resuming a session, updating framework tables, dispatching stage sub-agents, handling stop/pause/continue-from. |
session-entry-points.md | Initializing a session (any mode), loading project + module context, creating the PBI folder + context.md + test-session-memory.md, Team Discussion extraction rules, user-story workflow step order, bug Triage -> Verify -> Report workflow. |
acceptance-test-planning.md | Stage 1 Planning — generating the ATP (Acceptance Test Plan) for a ticket, Test Analysis structure, TC nomenclature {US_ID}: TC#: should <expected outcome> [<connector> <condition>] [given <precondition>], traceability creation + verification, and the Bug Analysis variant. |
feature-test-planning.md | Stage 1 Planning at feature / multi-story level — building a feature test plan, risk triage rubric, scenario decomposition, and variable + test-data identification. |
exploration-patterns.md | Stage 2 Execution — smoke-test Go/No-Go playbook, UI exploration on {{WEB_URL}}, API exploration on {{API_URL}}, DB cross-validation via {{DB_MCP}}, evidence naming + capture rules, edge-case checklist. |
reporting-templates.md | Stage 3 Reporting — ATR Test Report body, bug report template (summary, reproduction, severity, priority, labels), QA comment templates (story PASSED/FAILED, bug Template C/D), evidence-attachment guidance. |
../agentic-qa-core/references/session-management.md | Phase 0 + Session Start + per-stage checkpoints + Archive — resume contract, plan.md/progress.md schemas, archive policy, Engram per-phase checkpoint. This skill is a producer of session/sprint-testing/<scope>/... topic keys. |
Anti-patterns — NEVER do these
- S1. NEVER mark a Story Ready For Release (or transition to {{jira.status.story.qa_approved}}) without QA sign-off AND a signed-off ATR snapshot for audit trail.
- S2. NEVER skip the Stage 1 Test Plan (ATP) step in Modality jira-xray workflows — the Xray
Test Plan / Test Execution issues depend on the ATP being committed first; downstream TCs cannot link without it.
- S3. NEVER push test results to Jira without an ATR snapshot. The QA comment is a summary; the ATR is the audit record.
- S4. NEVER duplicate the ATR across Jira + Confluence (or any second store). Single source of truth — pick one per the modality decision in
.context/master-test-plan.md and link from anywhere else.
- S5. NEVER bypass the bug-triage decision tree (veto → risk-score → Severity + Root Cause) when a test fails. Every failure gets a triage before it becomes a Bug ticket.
- S6. NEVER write ATP / ATR bodies in raw ADF JSON by hand. Use md-to-adf via
[ISSUE_TRACKER_TOOL] so formatting survives Jira's renderer.
- S7. NEVER skip the smoke pass before triforce (UI / API / DB) exploration. Smoke validates the environment; triforce validates the feature. Order matters — a broken env produces false-positive bug reports.
- S8. NEVER mix UI + API + DB findings into a single bug ticket. File per layer (or per root-cause cluster) so triage and routing stay clean.
- S9. NEVER reuse a PBI folder across tickets. Every Story or Bug gets its own
.context/PBI/epics/EPIC-<KEY>-<slug>/stories/STORY-<KEY>-<slug>/ directory; cross-ticket contamination breaks evidence + traceability.
- S10. NEVER transition the ticket Ready For QA → In Testing without explaining the story to the user AND waiting for confirmation (CLAUDE.md §8 — Session Start is not a one-shot, it's a hand-off gate).
- S11. NEVER skip the auto-stage promote (Session Start → Stage 1 → Stage 2 → Stage 3) after a phase completes — each promote is a checkpoint that writes a
progress.md entry and feeds the next subagent's Context docs.
- S12. NEVER file a bug without a reproducible repro path AND evidence (screenshot, trace, log, network HAR, or DB row reference). "It failed for me once" is not a bug ticket.
- S13. NEVER hardcode
customfield_NNNNN IDs in ATP / ATR / QA comments or in any reference under this skill. Resolve every Jira field via {{jira.<slug>}} against .agents/jira-required.yaml.
- S14. NEVER hand-write a Jira-mirrored
.md in the PBI folder (story.md, acceptance-criteria.md, acceptance-test-plan.md, acceptance-test-results.md, comments.md, feature-test-plan.md, 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:) → run bun run jira:sync-issues get <KEY> --include-comments → READ the materialized file. Only context.md, test-session-memory.md, module-context.md, and evidence/ are hand-authored locally.
- 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.
Pre-flight checklist
