QA team onboarding

QA Test-Scenarios Author

A Wakeel agent that turns a Jira ticket into reviewable acceptance test scenarios — not automation code.

What we'll cover: how to trigger it, what it produces, how to refine its output, and where it stops so you stay in control.

Jira label → Wakeel → PR on QA repo → Jira comment

↓ Scroll, or use arrow keys

Scope

What this agent does — and where it stops

It's an author, not an automation engineer. You stay the gatekeeper for what gets scripted.

It does

Read Jira AC, Confluence pages, Figma frames — within ticket scope
Clone the QA repo + optional dev repos for API context
Produce Markdown scenarios + a traceability + coverage matrix
Open / update a PR on the QA repo with stable TC-IDs
Post a single Jira comment with the PR link + confidence summary

It does not

Generate Cypress / Appium / API test code or page objects
Expand scope beyond the ticket (Figma is supplementary, never authoritative)
Auto-create or transition Jira tickets
Open PRs on two QA repos in one run — exactly one target repo per run
Invent missing detail — gaps go into Open clarifications

Think of it as a senior QA peer that drafts the scenario doc for every ticket so you spend your time reviewing and challenging instead of typing.

Step 1 — Trigger

One label on the Jira ticket

That's the whole hand-off. The label is the contract.

Primary Jira label · initial generation

wakeel-qa-scenarios

Add this label to a Jira ticket that has Acceptance Criteria. The agent wakes up on the label-added event — not on every subsequent ticket edit.

Refine GitHub PR label

wakeel-refine-test-scenarios

Add this on the scenarios PR after you've left review comments. Agent re-reads feedback and updates Markdown in place. Removes itself after the run.

If your Jira project is linked to 2+ QA repos

Set the Wakeel QA Target Repo field on the ticket before labelling — value is owner/repo (GitHub URL also works). No default; the agent won't guess.

Also available: trigger from the Wakeel dashboard for backfill / dogfood without touching Jira labels.

Abort: if the scenarios PR is closed or converted to draft mid-run, the agent stops.

Re-run: remove and re-add the label to start over.

Step 2 — Routing

Which QA repo gets the PR?

Wakeel resolves a single PR target before any agent work starts.

Jira project FLT QA repos linked in Admin → Sources one chosen repo

1 link → auto-selected. 2+ links → Wakeel QA Target Repo field decides. No default — Wakeel refuses to guess.

If routing fails — Wakeel comments on Jira and stops

no_qa_repo

No QA repo linked to this Jira project → ask Wakeel admin to link one in Sources, then re-add the label.

missing_target_repo

2+ QA repos linked but the ticket has no Wakeel QA Target Repo — set it and re-label.

invalid_target_repo

Field value isn't a valid owner/repo or isn't in the linked list — comment lists what's valid.

field_not_configured

Wakeel admin hasn't wired the custom field ID yet — ping #wakeel.

Good news: every failure leaves you a Jira comment with exactly what to do next.

What happens behind the scenes

From label to PR in 7 steps

1

Webhook → ingest

Jira label-added event is validated, normalized, dispatched.

2

Routing resolved

QA repo selected (auto or via ticket field). On failure: Jira comment with guidance, event dropped.

3

Agent task queued

A run row appears in the Wakeel dashboard — visible immediately.

4

Before hooks deterministic

React on PR (if any), clone QA repo, create branch qa/{KEY}-test-scenarios, fetch Jira + Confluence + (refine) PR comments.

5

Agent run AI (Claude Opus)

Discover repo conventions → AC × axes → draft TCs → coverage matrix → write Markdown → push branch → open / update PR → comment on Jira.

6

After hooks deterministic

Feedback step on the PR. On refinement runs: removes the wakeel-refine-test-scenarios label.

7

Observability

Run streams live to the dashboard. The Jira comment links the run + PR.

The deterministic hooks sandwich the AI step — so cloning, branching, PR creation, and Jira posting are predictable and idempotent.

Inside the agent run

How it thinks about coverage

The agent encodes Almosafer QA philosophy — synthesized from qa-frontend-cypress, Appium automation, and qaBackend_CrossProduct.

AC × axes contract

Multiplies each AC by axes that matter — platform, channel, locale, currency, auth state, device. Each cell can become a TC.

Techniques applied

Equivalence Partitioning (EP), Boundary Value Analysis (BVA), Decision Tables (DT), State Transitions (STT), Error Guessing (EG), Use Cases (UC), Pairwise (PT), Cause-Effect (CE).

8 coverage dimensions

Functional, data, error/edge, integration, locale, accessibility, performance, security/privacy — walked every run, plus trigger-based extras.

Cap rule on confidence

Overall confidence is capped by the weakest covered dimension — no hand-wavy "HIGH" if any dimension is LOW.

Source priority: Acceptance Criteria → ticket description → linked Confluence / Sheets → Figma (UI detail only — never used to expand scope). If the AC is silent on something, the agent writes a clarification question — it doesn't invent.

Output

What you'll see on the PR

PR · QA repo

Title

FLT-1234 | Test scenarios — Add sort chips to flight results

Branch

qa/FLT-1234-test-scenarios

File

test-scenarios/FLT-1234/sort-chips.md

Label

wakeel-test-scenarios

Canonical sections in every scenario doc

01 Header + Jira link
02 Source documents
03 Test strategy
04 Resolved clarifications
05 Traceability (AC × axes → TC IDs)
06 Test cases (Summary, Type, Technique, Steps, Expected result, …)
07 Coverage matrix
08 Coverage gaps & residual risk
09 Self-challenge (3 audit prompts)
10 Overall confidence (cap rule)
11 Revision log (refinement runs only)

Four-element grammar — every Expected result names all four

UI

Observable product state (no selectors in prose)

API

Endpoint, status, payload — or explicit "no API call expected"

Success

Happy-path outcome

Error / edge

Negative — or explicit "no error path applicable"

Stable IDs: TC-01, TC-02, … — never renumbered across refinements. Reference them downstream like // FLT-1234 | TC-07.

Your review

What to check first

A short triage that beats reading the file top-to-bottom.

01

Open clarifications

If the agent flagged ambiguity, resolve it on the Jira ticket first — re-running on a fixed AC produces a much stronger doc.

02

Traceability table

Every AC should map to ≥ 1 TC. Empty rows mean the AC isn't covered yet.

03

Coverage gaps section

The agent admits what it didn't cover and why — read this before approving.

04

Confidence + cap rule

If overall confidence is LOW, find the dimension dragging it down and decide if it's acceptable for this ticket.

05

Expected results — four elements

Spot-check that UI, API, Success, Error/edge are each addressed (or explicitly waived).

06

Self-challenge prompts

The 3 audit prompts at the bottom show how the agent challenged its own draft — useful sanity check.

Refinement loop

Push back with review comments — re-trigger with one label

1

You review

Leave GitHub review comments on the scenarios PR — line-anchored or general.

2

Add label

wakeel-refine-test-scenarios on the PR.

3

Agent re-runs

Reads your comments + current diff, amends TCs or adds new ones at the next free TC ID — never renumbers.

4

Revision log

Appends ## Revision N — date, updates PR body, posts a Jira revision comment.

5

Loop until satisfied

Label is auto-removed after each run — add it again for another pass.

Tips for productive refinement

Be specific — quote the line, say what's wrong and what you expect instead.
If a TC is wrong, ask to amend it. If something's missing, ask for a new TC.
AC actually changed? Update Jira, then refine — the agent will re-read it.
Stable TC IDs are a feature — don't ask to renumber.

Cheat sheet

Labels you'll use

Label	Where you add it	What happens
wakeel-qa-scenarios	Jira ticket	Starts initial generation — once routing resolves to one QA repo.
wakeel-refine-test-scenarios	Scenarios PR (QA repo)	Re-runs the agent on your review comments. Removed automatically after the run.
wakeel-test-scenarios	Scenarios PR (auto)	Wakeel sets this on every PR it creates — handy for filtering in GitHub.

Jira field — only when needed

Wakeel QA Target Repo · text · value: tajawal/qa-frontend-cypress. Only required when 2+ QA repos are linked to your Jira project.

Branch convention

The agent always uses qa/{KEY}-test-scenarios — same branch is reused across refinements so the PR stays the same.

Known limits

What the agent won't do (yet)

Set expectations now — fewer surprises later.

One PR per run

Never two QA repos in one execution. Need both? File two tickets (one per QA repo).

Refinement failures = no Jira comment

If routing fails on a PR-label refinement, the event drops silently. Check the dashboard run log.

Confluence is capped

Max 8 pages and 64k characters per run. Link only the pages that matter.

No test code

Scenarios only. Automation script generation is the next agent on the roadmap.

Rollout plan

How we go from here to "everyone uses it"

1

Today

Routing + Jira field shipped. Agent seed lives in repo but enabled: false.

2

Dogfood

Pilot project (e.g. WAK → tajawal/wakeel) with a small QA cohort.

3

Per-project enable

Flights, Hotels, Activities, Mobile — each turned on once QA leads have ack'd the workflow.

4

Open to all

Default-on after the automation-script agent lands and we've burned in the refinement loop.

Pilot QAs

Label tickets, refine PRs, share what surprised you.

QA leads

Maintain your project's QA skills — conventions, coverage rules, and technique defaults.

Wakeel team

Iterate on the skill, link new repos, tune defaults from your feedback.

Q&A

Let's try it on a real ticket

Pick a ticket from your backlog with decent AC, add wakeel-qa-scenarios, and walk through the PR together.

Full agent guide index.html

#wakeel Slack channel

Wakeel dashboard live run logs

Wakeel — وكيل — Our AI Representative