shift-left-testing

Inputs

Read in order; stop earlier when the batch is small enough that later inputs add no signal.

1. .context/business/business-feature-map.md + .context/business/business-data-map.md + .context/business/business-api-map.md — domain vocabulary, entity model, CRUD matrix, auth model + endpoint contracts. Anchors refined ACs in real entities, flows, and API behavior. (All three are hard-required by the Readiness Preflight Gate + Phase 0.3.)
2. .context/master-test-plan.md — regression Epic + in-scope modules. Tells the refinement whether the Story falls inside an already-prioritized area.
3. The Story's Acceptance Criteria + **Source spec:** reference on Jira. Detailed read via bun run jira:sync-issues get <STORY_KEY> --include-comments, then read the synced acceptance-criteria.md (+ description). NEVER acli view for custom fields. Canonical input — every refined AC must trace back here.
4. .context/PBI/epics/EPIC-<KEY>-<slug>/stories/STORY-<KEY>-<slug>/ if a PBI folder already exists for this Story (created by a prior /sprint-testing cycle). Carries earlier session notes worth honoring.
5. .agents/jira-workflows.json — Story workflow + valid transitions (backlog -> shift_left_qa -> estimation). Source of {{jira.transition.story.*}} slugs used in Phase 3. ALSO the resolver for the [QA] Shift-Left Review tracking subtask: read it to confirm a subtask work type exists (+ its transitions) before Phase 1 creates any subtask; if the catalog has no subtask work type, the subtask steps are skipped with a warning — never blocked on.
6. .agents/jira-required.yaml — canonical slug catalog. Source of {{jira.acceptance_test_plan}} and other Jira field slugs touched in handoff.

---

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.

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

Shift-Left Testing — Pre-Sprint AC Refinement on a Backlog Batch

Drive Stage 0 — the pre-sprint Shift-Left loop — on a set of backlog Stories. Three phases, always in this order: Phase 1 Selection -> Phase 2 Refinement -> Phase 3 Handoff. Hand off afterwards to /sprint-testing once each Story reaches Ready For QA.

The skill is batch-by-design: one session refines N Stories from the backlog so PO + Dev lead can run a single grooming pass with the team. There is no single-issue mode — for a one-off urgent refinement, pass a list of length 1; the cadence stays the same.

---

Why this skill exists (separation from /sprint-testing)

Eje	/sprint-testing	/shift-left-testing
Cadence	In-sprint, ticket-by-ticket loop	Pre-sprint, batch grooming of N Stories
Entry status	{{jira.status.story.ready_for_qa}}	{{jira.status.story.backlog}} / shift_left_qa / estimation / ready_for_dev
Exit status	{{jira.status.story.qa_approved}} (full execution)	{{jira.status.story.estimation}} (refined, awaiting estimate by PO + Dev)
Audience	Dev + tester	PO / BA + tester (Dev lead optional)
Output	ATP + ATR + bugs + execution evidence	Refined ACs + risk map + pre-sprint ATP in the Story field (outlines only) + [QA] Shift-Left Review subtask + batch report
Execution	Smoke + UI / API / DB exploration	NONE — feature does not exist yet
Code reads	Deep, targeted (reproduce / verify)	Light (feasibility only — does the codebase support this?)
TC creation	Yes (TCs created in Stage 1)	No — Stage 4 (test-documentation) creates TCs after the Story ships
Sprint-testing later	Runs full pipeline	Short-circuits Phases 1-3 (label shift-left-reviewed detected) and just validates

The reuse story is deliberate: ~70% of the refinement logic already lives in sprint-testing/references/acceptance-test-planning.md Phases 1-3. This skill cites that reference instead of duplicating it — see Phase 2 below.

---

Dependencies

Requires agentic-qa-core. Loads on demand:

• agentic-qa-core/references/test-design-doctrine.md — MANDATORY before refining ACs or estimating outline coverage. A refinement that does not surface risk-beyond-AC and 1:N coverage is incomplete.
• agentic-qa-core/references/defect-management-doctrine.md — MANDATORY for the QA-Assignee hook (Part 2). This skill is the EARLIEST QA pickup of a backlog Story: when a QA takes a Story into Shift-Left refinement, set qa_assignee to the authenticated session user (self) — read-before-write, NEVER overwrite an existing owner except on explicit, justified handover. This skill still files NO Bug/Defect/Improvement (Phase 1 rejects non-Story types); only the QA-Assignee semantics of Part 2 apply here.
• 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 — cited inline by the sections that use them.

Compact Rules

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

• ACs are the FLOOR. Refinement's job is to push past the happy-path contract: surface the boundaries, exceptions, states, and anomalies the Story is silent on.
• 1:N is the default: a non-trivial AC implies multiple outlines (valid partition + each distinct invalid + boundaries + states). A 1-outline AC requires a written "trivially atomic" justification — never the default.
• Tag each refinement gap to a technique: ranges/limits → BVA; status/lifecycle fields → State-Transition; 2+ interacting conditions → Decision Table; 3+ combinable factors → Pairwise.
• A refined AC (Given/When/Then) is the business assertion; the outline (Should <behavior> <condition>) is its exploration. Keep them distinct.

Shift-left operational rules:

• Stories ONLY (no bugs — nothing to refine upstream). Entry status Backlog / Shift-Left QA / Estimation / Ready For Dev.
• Output = refined ACs + gap/ambiguity questions + the pre-sprint ATP in the {{jira.acceptance_test_plan}} field (outline NAMES + coverage estimate, no test code, no execution, NO Test Plan item — /sprint-testing Stage 1 creates the item from the field) + the closed [QA] Shift-Left Review subtask + the batch report.
• Tracking subtask [QA] Shift-Left Review per accepted Story: find-or-create in Phase 1 (transition to In Progress), close in Phase 3 handoff (transition to Done). Exhaustive session annotations (long analysis, refinement traces) go on the SUBTASK, keeping the Story clean. Work type + transitions resolved from .agents/jira-workflows.json; no subtask work type in the catalog → skip with a warning, never block.
• The heart of the skill (Phase 2) = edge cases not in story + ambiguities + gaps — feed them to PO/Dev as questions AND as derived outlines.
• On taking a Story into refinement (first QA pickup), set qa_assignee to self — read-before-write, never overwrite an existing owner (agentic-qa-core/references/defect-management-doctrine.md Part 2). This skill files NO Bug/Defect/Improvement; only the QA-Assignee hook applies.
• On completion: add label shift-left-reviewed; transition Backlog → Shift-Left QA → Estimation.

Read full SKILL.md when: running the batch grooming pipeline, writing the per-Story shift-left-refinement.md, or handling the PO/Dev handoff.

---

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 is per-batch scope: <scope> = <YYYY-MM-DD>-<descriptor> (e.g. 2026-05-20-payments-area). Session state lives at .session/shift-left-testing/<YYYY-MM-DD>-<descriptor>/{plan.md, progress.md} per agentic-qa-core/references/session-management.md §3 + §9. The per-Story shift-left-refinement.md files stay under each Story's PBI folder ([LOCAL] staging buffer for Phase 2 → Phase 3 — disposable once Phase 3 publishes to Jira; see references/atp-outline-template.md and .context/PBI/README.md).

This skill is compliant with the doctrine in AGENTS.md §"Orchestration Mode (Subagent Strategy)" and the session contract in .agents/skills/agentic-qa-core/references/session-management.md. Every dispatch follows the 7-component briefing format defined in .agents/skills/agentic-qa-core/references/briefing-template.md, and the pattern selected per phase matches the decision guide in .agents/skills/agentic-qa-core/references/dispatch-patterns.md.

Phase	Pattern	Subagent role
Phase 1 — Selection	Single	Backlog Selection subagent: pull candidate Stories via [ISSUE_TRACKER_TOOL], apply veto + risk-score triage, return ranked candidate table. After user OK: find-or-create the [QA] Shift-Left Review subtask under each accepted Story + transition it to In Progress (skip with warning if the catalog has no subtask work type)
Phase 2 — Refinement (per Story)	Sequential — looped per Story	Refinement subagent: load acceptance-test-planning.md Phases 1-3 + outline-only Phase 4, write shift-left-refinement.md, append PO/Dev questions, return summary block. ONE subagent per Story. NEVER parallel across Stories (each subagent writes a different PBI file but the orchestrator must present each summary to the user sequentially before the next dispatch)
Phase 3 — Handoff (per Story)	Sequential — looped per Story	Handoff subagent: update Jira description + {{jira.acceptance_test_plan}} custom field (both modalities — no Test Plan item pre-sprint) + handoff comment + labels + subtask annotations + subtask transition to Done + Story transition backlog -> shift_left_qa -> estimation. Returns transition log + trace verification
Phase 3 — Batch report	Single	Batch Report subagent: aggregate per-Story summaries into .session/shift-left-testing/<batch-id>/batch-report.md + post to parent epic if Stories share one

Sequential by design. Phase 2 refinement looks parallelizable (each Story is independent in Jira), but the orchestrator must present each Story's refinement summary to the user before moving on. This keeps the user in the loop, lets them veto a Story mid-batch, and matches the team-grooming cadence the skill is designed for. Parallelism would burn the user's attention budget.

On any subagent failure: STOP, report the partial state (which Stories refined, which Jira mutations landed), present retry / skip-story / abort options. Do NOT auto-fix nor auto-rollback. Jira mutations are recorded in the batch report so partial sessions are resumable. See .agents/skills/agentic-qa-core/references/orchestration-doctrine.md.

---

Workflow — one pipeline, three phases

Phase 0 — Session resume check + Session Init (always first)
    -> Check .session/shift-left-testing/<batch-id>/progress.md → offer resume / restart / abort
    -> Resolve TMS modality (A: Xray / B: Jira-native — recorded for Stage 1; the
       pre-sprint ATP write is field-first in BOTH modalities)
    -> Load /acli (no /xray-cli — this skill creates no TMS items)
    -> Verify project-wide context files
    -> Resolve candidate list (explicit IDs OR backlog JQL)
    -> Create session folder .session/shift-left-testing/<YYYY-MM-DD>-<descriptor>/
       (writes plan.md after candidate list confirmed; progress.md appended per phase)

Phase 1 — Selection
    -> Detailed-read each candidate via `bun run jira:sync-issues get <STORY> --include-comments`
       (batch: `jql "<backlog JQL>"`), then read the synced .md
    -> Reject non-Story types (Bug / Spike / Sub-task / Tech-debt)
    -> Apply veto + risk-score triage per candidate
    -> Present ranked candidate table -> WAIT for user OK
    -> Per accepted Story: find-or-create subtask "[QA] Shift-Left Review"
       -> In Progress (skip + warn if no subtask work type in the catalog)

Phase 2 — Refinement (loop per accepted Story)
    -> Dispatch Refinement subagent: produce shift-left-refinement.md
       (Critical Analysis + Story Quality Analysis + Refined ACs + ATP outlines)
    -> Reuses sprint-testing/references/acceptance-test-planning.md §Phases 1-3
       with shift-left-mode delta (no test-data generation, no parametrization tables, outline names only)
    -> Present per-Story summary -> WAIT for user OK before next Story

Phase 3 — Handoff
    -> Per Story sequentially:
         - Update Jira description with "QA Refinements (Shift-Left Analysis)"
         - Populate the ATP field {{jira.acceptance_test_plan}} (both modalities;
           fallback: "## Acceptance Test Plan (ATP)" comment when the field is absent.
           NO Test Plan item — /sprint-testing Stage 1 creates it from the field)
         - Labels: shift-left-reviewed + shift-left-{YYYY-MM-DD}
         - Transition: backlog -> shift_left_qa (analyze) -> estimation (estimate)
         - Subtask "[QA] Shift-Left Review": post session annotations -> Done
         - Verify trace
    -> Batch report posted to .session/shift-left-testing/<batch-id>/batch-report.md
       + posted as comment on parent epic if Stories share one
    -> Archive: orchestrator moves .session/shift-left-testing/<batch-id>/ to
       .session/.archive/<YYYY-MM-DD>-shift-left-testing-<batch-id>/
       per agentic-qa-core/references/session-management.md §8

---> Cross-skill handoff (NOT this skill):
       When each Story later reaches Ready For QA:
         /sprint-testing reads label `shift-left-reviewed` and short-circuits
         Phases 1-3 to validation-only (sprint-testing/references/acceptance-test-planning.md §Phase 0).
         Stage 1 ALSO creates the Test Plan item (`ATP: {STORY-KEY}: {title}`)
         FROM the {{jira.acceptance_test_plan}} field content — the item is
         in-sprint work, never pre-sprint.

---

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 — treat anything the user already stated (the Story IDs, the modality, "groom the backlog") as provided args; ask only real gaps. (2) probe, don't assume. Surface gaps + REDs as ONE AskUserQuestion checklist; self-fix with approval + explanation; STOP on any blocking RED. This skill does NO live execution (no env/DB/API/browser), so its gate is light — it is mostly a tooling + context readiness check. 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
Issue-tracker ([ISSUE_TRACKER_TOOL])	REQUIRED	All refinement output lands on Jira (description, ATP field, comment, labels, transitions). Load /acli; validate setup via bun run jira:check.
TMS modality resolved	REQUIRED	Recorded in plan.md and carried into the handoff so /sprint-testing Stage 1 knows which engine will materialize the Test Plan item later. The pre-sprint ATP write itself is modality-independent — field-first in both. 4-step probe; ask only if all auto-checks fail.
/xray-cli + XRAY_* creds	NOT NEEDED	Shift-Left creates no TMS items in either modality. The pre-sprint ATP lives in the {{jira.acceptance_test_plan}} field (fallback: comment); the Test Plan item is created by /sprint-testing Stage 1 from the field content.
Business context files	REQUIRED	.context/business/* + .context/master-test-plan.md — refinement without them produces low-value questions. Missing → hand off to /project-discovery.
Candidate Story list	REQUIRED	Explicit IDs (args) or a backlog JQL. Confirm size with the user before Phase 1.

Env reachability, test-user creds, DBHub, OpenAPI/API_TOKEN, Playwright and resend are N/A here — shift-left never executes against a running system. After the gate clears (all REQUIRED GREEN), continue to Phase 0 below.

---

Phase 0 — Session resume check + Session Init

0.0 Session resume check (per agentic-qa-core/references/session-management.md §4). Compute <batch-id> = <YYYY-MM-DD>-<descriptor> from the invocation context. Check .session/shift-left-testing/<batch-id>/progress.md. If it exists, read plan.md + the tail of progress.md, surface the last completed phase + next planned phase + any blocking notes, and offer resume / restart / abort. On restart, archive the current directory to .session/.archive/<YYYY-MM-DD>-shift-left-testing-<batch-id>-aborted/ before proceeding. On abort, stop here.

0.1 Resolve TMS modality. Same 4-step probe as sprint-testing Session Start (test-documentation/SKILL.md §Phase 0). Persist the result in .session/shift-left-testing/<batch-id>/plan.md (under the ## Inputs H2 — the plan.md is the canonical record per session-management §6).

0.2 Load required tool skills:

• Always load /acli (custom-field update, comment, transition, label, subtask create — all writes; plus the trivial key+summary+status candidate search). Story DETAIL reads (description, ACs, scope, comments, parent epic) go through bun run jira:sync-issues get/jql — NOT acli view.
• /xray-cli is NOT loaded by this skill. Shift-Left creates no TMS items in either modality: the pre-sprint ATP lives in the {{jira.acceptance_test_plan}} custom field (fallback: the ## Acceptance Test Plan (ATP) comment when the field is absent). The Test Plan ITEM is created by /sprint-testing Stage 1 from the field content, once PO has estimated and the Story enters the sprint.
• Both modalities: /acli alone covers every write this skill performs.

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.3 Verify project-wide context files exist:

• .context/business/business-data-map.md
• .context/business/business-feature-map.md
• .context/business/business-api-map.md
• .context/master-test-plan.md

If any of these is missing, STOP and hand off to project-discovery (or the individual /business-*-map and /master-test-plan commands). Shift-left refinement without business context produces low-value PO/Dev questions and bloats the batch report.

0.4 Resolve the candidate Story list. Two modes:

• Explicit IDs — user passes UPEX-100,101,102,103 (or any natural-language list of Story keys). Use these verbatim; no JQL.
• Backlog JQL — user says "groom the backlog" with no IDs. Build a JQL via [ISSUE_TRACKER_TOOL] filtering on:
  • project = {{PROJECT_KEY}}
  • issueType = Story
  • status in ({{jira.status.story.backlog}}, {{jira.status.story.shift_left_qa}}, {{jira.status.story.estimation}}, {{jira.status.story.ready_for_dev}})
  • Optionally sprint in openSprints() if the user says "next sprint candidates"
  • Sort by Priority DESC, then Created DESC
• Confirm the resolved list size with the user before Phase 1 starts. A batch of 1-12 Stories is the practical sweet spot; >12 should be split into multiple sessions.

0.5 Create the session folder + write plan.md:

.session/shift-left-testing/<YYYY-MM-DD>-<descriptor>/
  plan.md                # session-management.md §6 schema — Goal, Inputs, Approach,
                         #   Phase breakdown, Risks, Verification checklist, Cross-references.
                         #   Inputs includes TMS modality + candidate list.
  progress.md            # append-only, one entry per phase (§7 schema)
  candidates.md          # Phase 1 output (domain artifact)
  batch-report.md        # Phase 3 final output (domain artifact)
  # Per-Story refinement files live under each Story's own PBI folder,
  # NOT inside the session folder:
  #   .context/PBI/epics/EPIC-<EPIC_KEY>-<slug>/stories/STORY-<STORY_KEY>-<slug>/shift-left-refinement.md

The <descriptor> is kebab-case (e.g. morning, payments-area) and lets two sessions on the same day stay independent.

After this step, append the first entry to progress.md: ## Phase 0 — Session Init — <ISO-8601 UTC> with status: completed, next: Phase 1 — Selection. Subsequent phases follow the same shape per agentic-qa-core/references/session-management.md §7.

---

Phase 1 — Selection

Decides which Stories actually enter the refinement loop and at what depth.