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: .agents/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, 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/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 <expected outcome> [<connector> <condition>] [given <precondition>]; Validate <feature> 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.

---

Mode routing

Resolve mode before the readiness preflight and Phase -1 session workflow.

• repair-traceability: selected only by the legacy fix-traceability alias or an explicit request to repair a ticket's existing traceability. Forward $ARGUMENTS unchanged and load only references/repair-traceability.md. Preserve its sealed sequence: audit -> present plan -> explicit user approval -> apply -> verify. Do not start Analyze -> Prioritize -> Document, create unrelated test cases, or broaden the ticket scope.
• document (default): normal TMS documentation, ROI, and Candidate/Manual/Deferred work. Continue with the workflow below.

If the user has not supplied the ticket key required by repair-traceability, ask for it before any TMS call. Missing credentials remain a hard stop under AGENTS.md Critical Rule #10.

---

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-scope: <scope> = <JIRA-KEY> (ticket / bug scope), <module-slug> (module scope), or <YYYY-MM-DD>-adhoc (ad-hoc scope). Session state lives at .session/test-documentation/<scope>/{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 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 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/<scope>/progress.md if present, offers resume / restart / abort per agentic-qa-core/references/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 <-> ATS/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 .agents/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 <scope> from invocation: <JIRA-KEY> for ticket/bug scope, <module-slug> for module scope, <YYYY-MM-DD>-adhoc for ad-hoc. Then:

1. Check .session/test-documentation/<scope>/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/<YYYY-MM-DD>-test-documentation-<scope>-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 AGENTS.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 AGENTS.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
ATS (Acceptance Test Set)	Test Set issue titled ATS: {US_ID}: {story title}, mandatory per Story — holds ALL the Story's TCs (membership Xray-internal), linked to the US (is tested by — the coverage-panel link)	Same Test Set issue when the work type is present — membership expressed as TC→ATS issue links (the "membership is never a link" rule is xray-only). Work type absent → no ATS: direct TC→Story links (cascade last resort)
TS / Precondition / Test Plan	First-class Xray issue types (TS: feature Set is optional grouping)	Same native work types when present in the instance; absent → 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/<scope>/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 each scope

Pick the scope based on the input, not the output. All four scopes share the same Analyze -> Prioritize -> Document pipeline; only the input source and defaults differ.

Scope	Input	Typical volume	Default labels	Notes
Module-driven	A module of the system explored end-to-end	20-100+ scenarios	regression, e2e or integration	Batch of TCs grouped under the Regression Epic. Most scenarios will be Deferred.
Ticket-driven	A QA Approved user story from a sprint	3-8 scenarios	regression, plus the test type	Output of a sprint-testing session. ATP/ATR created per US.
Bug-driven	A closed bug with a verified fix	0-2 scenarios	regression, automation-candidate (usually)	Run the Bug-driven decision (below). Not every bug qualifies; if it does, reuse the existing failed Test or create one — an important bug must end with a Test. ROI biased up: "it failed once, it can fail again."
Ad-hoc / Exploratory	New scenarios found in exploratory testing	1-10 scenarios	regression	Apply the 3 Phase-0 questions harshly; ad-hoc scenarios are often one-time validations.

If the user gives you a story ID, use ticket-driven. If they give you a bug ID, use bug-driven. If they give you a module name or a session output, use module- or ad-hoc accordingly.

Bug-driven decision — "an important bug must have a test" (GOLDEN RULE)

Not every bug becomes a regression Test — a one-time typo in a stable area is treated like a failed test (the fix was verified in sprint-testing) and Deferred. But run the same analysis + prioritization you'd run on any scenario; if the bug IS regression-worthy, it MUST end with a Test that covers it, in BOTH modalities. Where there is an important bug, there must be a test that catches it again — this rule is worth gold.

1. Is this Bug/Defect a regression candidate?  (apply Phase-0 filter + ROI; the prior-bug rule biases up)
   NO  -> No new Test. Treat as a failed test: fix already verified in sprint-testing -> log as Deferred. Done.
   YES -> step 2.

2. Was the bug found FROM an existing, already-executed Test?  (a Test that ran and failed — jira-native OR xray)
   YES -> REUSE that existing Test for the bug's retest + regression. It already lives in the test set;
          ensure it is linked to the bug (`tests / is tested by`) and promoted into regression. Do NOT duplicate.
   NO  -> CREATE + design the corresponding Test for the bug's retest.
          jira-native: new `Test` issue.  jira-xray: new Xray `Test` (+ plugin-appropriate Test Plan / Test Set linking).
          Link to the bug via `tests / is tested by`.

This overrides sprint-testing's "the bug is the test case" — that phrase covers only the immediate in-sprint retest, NOT future regression. The retest reproduces+verifies the fix now; this rule decides whether a persistent Test must exist (reuse or create) so the bug can never silently return.

Scope handoff to /test-automation. The Candidate TCs produced here flow downstream to /test-automation, which re-scopes them into its own 3 planning scopes: module-driven → Module (Macro), ticket-driven → Ticket (Medium), bug-driven → Regression-driven (Micro). ad-hoc / exploratory Candidates have no 1:1 automation scope — they enter under whichever fits (a module batch, or regression-driven for a single TC). Manual and Deferred verdicts are terminal and never reach automation.

After scope confirmation, write .session/test-documentation/<scope>/plan.md per agentic-qa-core/references/session-management.md §6 — Goal (scope + TMS modality + expected TC count), Inputs (PBI references, ATP source, prior bugs), Approach (per-phase dispatch table above), Phase breakdown (Phase 1 Analyze → Phase 2 Prioritize → Phase 3 TC creation with chunk count → Traceability → Final report), Risks, Verification checklist (all TCs created with traceability + coverage matrix written), Cross-references (.context/PBI/epics/EPIC-<KEY>-<slug>/stories/STORY-<KEY>-<slug>/test-cases/*.md per-TC files + .context/reports/ coverage matrix). Append ## Phase -1 — Session resume check — <ts> with status: completed, next: Phase 0 — Resolve TMS modality to progress.md.

---

Phase 1 — Analyze

Inputs you must gather