Test Documentation

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

Test Documentation — QA Bridge

Take already-validated tests and formalize them in the TMS (Jira, Xray, or equivalent) with full traceability, the right priority, and a clear automation verdict.

Three phases, always in this order: Analyze -> Prioritize (ROI) -> Document. Never skip prioritization: most scenarios should end up Deferred, not automated.

One hard prerequisite: the tests being documented must describe behavior that was already validated ({{jira.status.story.qa_approved}} story, closed bug, or finished exploratory session). The TMS is a documentation and regression-protection tool, not an exploration tool.

---

Dependencies

Requires agentic-qa-core. Loads on demand:

• agentic-qa-core/references/test-design-doctrine.md — MANDATORY before deriving TCs from acceptance criteria. Governs the 1:N TC explosion, the formal-technique triggers, and the floor-not-ceiling coverage model. EP + BVA are operationalized here against the canon.
• agentic-qa-core/references/defect-management-doctrine.md — MANDATORY before parenting a Test or raising an Improvement. Governs QA process-epic parenting (every Test hangs from the QA Test Repository epic, Part 4), the mandatory components axis (Part 3), and the Improvement bridge for under-specified ACs (Part 1). This skill files no Bugs.
• agentic-qa-core/references/briefing-template.md, ./dispatch-patterns.md, ./orchestration-doctrine.md, ./session-management.md, ./preflight-gate.md, ./traceability-linking.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):

• Documenting an AC→TC map is the FLOOR (≥1 TC per AC is a minimum, never a target). Coverage = AC-conformance + risk-beyond-AC; the TC set must include boundary / negative / state / anomaly cases the AC is silent on.
• 1:N applies to DERIVATION (consider many cases by technique), not to the REGRESSION repository. Only regression-worthy scenarios (Candidate/Manual) are persisted there; most are Deferred. jira-native: Stage 4 CREATES Tests for those only (Deferred = report-only). jira-xray: sprint Tests already exist (Stage 1) — Stage 4 PROMOTES the regression-worthy into the Test Plan + enriches them. Document because it will be re-run, never to hit a count.
• 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.
• Parametrize for artifact economy: same-behavior data variants → ONE Test (Scenario Outline + Examples rows) per partition, NOT N separate Tests; split only when action / outcome / status / state differs. (Canon: doctrine §"Part 2.5".)
• Cross-cutting characteristics (XSS, perf, a11y) deferred to app-level suites are an EXPLICIT handoff, not a silent drop — name the receiving suite or file the gap.

Test-documentation operational rules:

• Documents already-validated behavior only — not an exploration tool (exploration belongs to /sprint-testing).
• TC identity = Precondition + Action + verifiable outcome. Naming (TC): {US_ID}: TC#: should [ ] [given ]; Validate is reserved for the GROUPING layer (Test Set summary / describe()). Reject "Login test", "Login - error", "TC1: Test form".
• ROI formula → one of three verdicts per TC: Candidate (feeds test-automation), Manual, Deferred. Prioritize by risk.
• Cardinality: US→TC is 1:N; AC→TC is N:1 or N:M. Resolve TMS modality (Xray vs Jira-native) in Phase 0 before documenting.
• Bug-driven (GOLDEN RULE): not every bug is a regression TC, but a regression-worthy bug MUST end with a Test — REUSE the existing failed Test if it came from one, else CREATE one (both modalities). A non-qualifying bug is treated like a failed test → Deferred, no new Test.

Read full SKILL.md when: resolving TMS modality, computing ROI, writing Gherkin, or wiring US-ATP-ATR-TC traceability links.

---

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///, 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 is per-scope: ` = (ticket / bug scope), (module scope), or -adhoc (ad-hoc scope). Session state lives at .session/test-documentation//{plan.md, progress.md} per agentic-qa-core/references/session-management.md` §3 + §9.

Naming collision note: this skill already owns ## Phase 0 — Resolve TMS modality (the TMS gate). The session resume check is therefore named ## Phase -1 — Session resume check to avoid colliding with the existing Phase 0 anchor. Resume fires FIRST, then the TMS modality gate, then the rest of the pipeline.

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 phase matches the decision guide in .claude/skills/agentic-qa-core/references/dispatch-patterns.md. Phase 1 (Analyze) and Phase 2 (Prioritize) stay inline because planning and decisions live in the orchestrator; the only Parallel hotspot is bulk TC creation in Phase 3, which is also the only step that branches per TMS modality.

| Phase | Pattern | Subagent role | |--------------------------------------------------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------| | Phase -1 — Session resume check | inline | orchestrator only; reads .session/test-documentation//progress.md if present, offers resume / restart / abort per ./session-management.md §4 | | Phase 0 — Resolve TMS modality | inline | orchestrator only; existing 4-step probe — unchanged | | Phase 1 — Analyze scope | Single | inline — planning lives in the orchestrator (anti-pattern to delegate) | | Phase 2 — ROI / Candidate-Manual-Deferred verdict | Single | inline — decisions live in the orchestrator | | Phase 3 — TMS TC creation (N > 10 TCs) | Parallel | M subagents, chunks of ~5-10 TCs per agent; cap = 10 to avoid Jira/Xray rate limits; each subagent loads /xray-cli (Modality jira-xray) or /acli (Modality jira-native) | | Phase 3 — TMS TC creation (N ≤ 10 TCs) | Single | inline — dispatch overhead is not justified for small batches | | Phase 3 — Traceability linking (US ATP ATR TCs) | Single | inline — requires aggregated state of all created entities | | Phase 3 — Final report / coverage matrix | Single | inline — synthesis lives in the orchestrator |

• Concurrency cap = 10 subagents for Parallel TC creation. Jira and Xray APIs both rate-limit at ~10 writes/sec sustained; fanning out wider triggers 429 responses. If a module has >100 TCs, batches per subagent must be larger than 10 each (cap is on subagent count, not chunk size).
• Error protocol: On any subagent failure: STOP, report the partial success state (which TCs landed, which failed, with their issue keys / errors), present retry / skip / abort options. Do NOT auto-fix nor auto-rollback. See .claude/skills/agentic-qa-core/references/orchestration-doctrine.md.

---

Readiness Preflight Gate (MANDATORY — runs before Phase -1)

> Full doctrine: agentic-qa-core/references/preflight-gate.md. Runs FIRST, before the resume check and before the TMS-modality gate. Two laws: (1) args-as-answers — the scope (module / ticket / bug / ad-hoc) and any stated modality are provided args; ask only the 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 documents already-validated behavior in the TMS — it does NOT execute against a live system, so its gate centers on TMS write capability. 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 | TC / ATP / ATR creation, linking, transitions. Load /acli; validate via bun run jira:check. | | TMS modality + [TMS_TOOL] | REQUIRED | The whole Phase 0 gate. jira-xray → /xray-cli loaded + XRAY_* creds set + Xray issue types present. jira-native → /acli covers it. Resolve before Phase 1; ask only if all auto-checks fail. | | Source repos readable | OPTIONAL | Phase 1 source-code validation reads backend/frontend code, not a running env — no live-env or DB/API/browser probe needed. |

Active env, test-user creds, DBHub, OpenAPI/API_TOKEN, Playwright, resend and kata-manifest.json (an automation-only concern owned by /test-automation) are N/A — documentation never hits a live system nor writes test code. After the gate clears (all REQUIRED GREEN), continue to Phase -1 below.

---

Phase -1 — Session resume check (MANDATORY, inline)

Runs BEFORE Phase 0 (TMS modality gate). Compute prospective ` from invocation: for ticket/bug scope, for module scope, -adhoc` for ad-hoc. Then:

1. Check .session/test-documentation//progress.md.
2. If it does NOT exist → proceed to Phase 0 (TMS modality).
3. If it DOES exist:

• Read plan.md (chosen scope, TMS modality, TC list, ROI verdicts).
• Read tail of progress.md (last completed phase + next planned phase).
• Surface to the user: scope, TMS modality, last completed phase, next phase, any pending TC creation chunks that did not finish (the most common interruption point — Phase 3 parallel bulk create capped at 10 subagents).
• Offer resume / restart / abort. On restart, archive to .session/.archive/-test-documentation--aborted/ first.

Critical resume case: Phase 3 parallel bulk create interrupted mid-batch. The progress.md records per-chunk completion (one entry per Parallel subagent return), so resume skips already-created TCs by reading the chunks marked completed and dispatching only the missing chunks. This is why per-subagent checkpoint matters (see Phase 3 below).

---

Phase 0 — Resolve TMS modality (mandatory gate)

Every project runs in one of two modalities. Resolve it before Phase 1. The same ATP/ATR/TC concepts have different containers in each mode.

The question you MUST answer first

Does this project have Xray installed and licensed on Jira?
  A. Yes -> Modality jira-xray
  B. No  -> Modality jira-native (no Xray)

How to resolve it without asking (in order)

1. Check CLAUDE.md for {{TMS_CLI}}. Value bun xray (or any Xray CLI) -> Modality jira-xray. Value is unset, acli-only, or {{TMS_CLI}} matches {{ISSUE_TRACKER_CLI}} -> Modality jira-native.
2. If CLAUDE.md is ambiguous, look for a .context/master-test-plan.md line such as TMS: Xray on Jira or TMS: Jira native.
3. If still ambiguous, list existing issue types in the project via [ISSUE_TRACKER_TOOL] List issue types. If the project exposes Test Plan / Test Execution / Test Set / Pre-Condition, it is Modality jira-xray. Otherwise Modality jira-native.
4. Only if all three checks fail, ask the user the question above. Do NOT ask by default — autoresolve first.

What changes per modality

| Artifact | Modality jira-xray | Modality jira-native | |----------|---------------------------|---------------------------| | ATP (Acceptance Test Plan) | Test Plan issue titled ATP: {STORY-KEY}: {story title}, parented to the QA Master Test Plan epic, linked to the US | Same Test Plan issue by excellence (native Jira work type, Xray-independent); falls back to the Story {{jira.acceptance_test_plan}} field (then a ## Acceptance Test Plan (ATP) comment) only when the Test Plan work type is absent from the instance. | | ATR (Acceptance Test Results) | Test Execution issue with Test Runs per TC, Environment, Begin/End Date, titled ATR: {STORY-KEY}: Story Testing, parented to the QA Test Artifacts epic | Same Test Execution issue by excellence; falls back to the Story {{jira.acceptance_test_results}} field (then a ## Acceptance Test Results (ATR) comment) only when the Test Execution work type is absent from the instance. | | TC (Test Case) | Xray Test issue (type Manual / Cucumber / Generic) | Jira-native Test issue type (or Task with custom type), Description carries the full TC template | | Test Set / Precondition / Test Plan | First-class Xray issue types | Not available — use labels + Epic grouping | | Result sync | CI imports JUnit/Cucumber via [TMS_TOOL] Import Results -> Test Runs auto-update | Custom script updates Test Status field on each TC + comment with build context | | CLI tag | [TMS_TOOL] resolves to bun xray or equivalent | [TMS_TOOL] falls through to [ISSUE_TRACKER_TOOL] (acli / Jira MCP) |

Persist the decision

Once resolved, save the modality into .session/test-documentation//plan.md §Inputs (canonical session record) and ALSO mirror to test-session-memory.md for the ticket (if one exists, for per-ticket sub-agent context). Treat as sticky: do not re-resolve mid-session. If you detect drift (e.g. [TMS_TOOL] suddenly fails), stop and ask the user before re-resolving.

Reference implementations:

• Modality jira-xray concepts + Xray REST/GraphQL/CLI -> references/xray-platform.md
• Modality jira-native project setup (Test issue type, Screen Scheme, custom fields) -> references/jira-setup.md
• Both modes side-by-side (field mapping, workflow, Description template) -> references/jira-test-management.md

---

When to use

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: upex-galaxy
• Source: upex-galaxy/agentic-qa-boilerplate
• License: MIT

Install and usage instructions live in the source repository linked above.