How to control scenario tagging

When you'd do this: when you want generated scenarios to carry consistent, defined metadata rather than ad-hoc labels — and you want the team (or the build agent) reading those scenarios downstream to interpret them the way you meant.

Every scenario REQQA generates is annotated with Gherkin tags — the @ labels that sit above a Feature:, Rule:, or Scenario: line:

@feature:member-invitation @req:FR-20.4 @priority:high
Feature: Invite a team member

  @happy-path @test:required @automation-ready
  Scenario: Administrator invites a new member by email
    ...

  @error-path @validation @test:required
  Scenario: Invitation to an address already in the organisation
    ...

Tags are how a story tells a reader what kind of test each scenario is — which are happy paths, which probe boundaries, which touch security, and which are mandatory for the acceptance gate. They are written by the story generator, not by hand, so controlling the tagging means controlling the inputs to generation.

There are three levers, and they work at different levels. This page covers all three, plus the review step for tags the AI invents.

Lever	What it controls	Where you set it	Scope
Tag glossary	Which tags exist and what each one means	Stories → Tags	Your organisation
Test strategy	How @test:* tags are assigned	Application edit page	One application
Provenance tags	@feature:, @req:, @priority:	Fixed in the generation prompt	System-wide

For the concepts behind tags and where they sit in the story model, see Stories and features.

Before you start

• You must be a member of an organisation (the tag glossary is org-scoped).
• To change a test strategy you need edit rights on the application.
• Tag changes affect future generation only. Stories already generated keep the tags they were given — regenerate a story if you want it re-tagged.

The system vocabulary

REQQA ships 25 system tags in five categories. They are shared by every organisation and cannot be deleted.

Category	What the tags describe	Examples
Scenario purpose	The role the scenario plays	@happy-path, @error-path, @boundary, @edge-case, @alternate-path
Test characteristic	The property under test	@validation, @access-control, @concurrency, @idempotency, @data-integrity, @performance
Data condition	The shape of the input	@empty-input, @invalid-input, @min-value, @max-value, @large-dataset
Risk	Why the scenario matters	@risk:security, @risk:data-loss, @risk:performance, @risk:compliance, @risk:integration
Test strategy	Its place in the acceptance gate	@test:required, @test:optional, @test:holdback, @automation-ready

A scenario normally carries several tags at once — one purpose tag, one or more characteristic or data-condition tags, a risk tag where relevant, and a test-strategy tag.

Lever 1 — tune the vocabulary

Open Stories → Tags from the navigation to reach the Tag Glossary. The page lists the system tags grouped by category, each with its definition, its usage notes, and a Status of System or Override.

The definitions are not decoration. The whole glossary — every tag name, definition, and usage note — is injected into the story-generation prompt. When the AI decides whether a scenario is @boundary or @edge-case, it is reading the text on this page. Editing a definition changes how the tag gets applied.

Override a system tag's definition

Use this when a system tag is the right name for your team but the shipped definition doesn't match how you use it.

1. Find the tag and click Override.
2. Edit the definition and, optionally, the behavioural usage note. Write it as an instruction to the generator: say what the tag covers and what it excludes.
3. Save. The row is highlighted and its status changes to Override, with the system default still shown beneath your text for comparison.

Your override applies to everyone in your organisation, and only within your organisation.

Reset an override

Click Reset on an overridden row to drop back to the system definition. This removes the override only — it does not touch any story already tagged with it.

Add an organisation tag

Click Add Org Tag to define vocabulary of your own — a regulatory category, a subsystem marker, a house convention. Give it a name (without the @), a category, a definition, and usage notes.

A custom tag appears on the glossary in alphabetical position among the system tags of its category — marked Custom — and is sent to the generator on the same terms as a system tag. It is visible only to your organisation.

Naming rules:

• 1–64 characters of letters, digits, hyphen, underscore and colon
• a colon separates a namespace (risk:security, acme:legacy-integration) and may not begin or end the name, or appear twice in a row
• the name may not begin with a digit
• a leading @ you type is stripped before the name is stored

note

A custom tag may not take the name of a system tag. If you try, the page will say so and point you at the override workflow — overriding is the only way to change what a system tag means, so a custom tag can never quietly shadow one.

Lever 2 — set the test strategy

The @test:* tags are not chosen from the glossary — they are assigned by a per-application policy. Open the application's edit page and find Test strategy under Story Generation:

• A) All mandatory — every scenario is tagged @test:required. The developer must execute all of them as part of the acceptance gate.
• B) Selective mandatory — the AI judges which scenarios are high-value and tags those @test:required; the rest get @test:optional. The developer runs the tagged subset.
• C) All mandatory plus holdbacks — every scenario is @test:required, and the AI additionally marks a subset @test:holdback — scenarios that verify critical business rules from an end-user perspective, intended for independent customer verification rather than the developer's own run.

Strategy A is the default and applies when nothing is set. Choose B when you have enough volume that running everything is uneconomic, and C when you want to keep an independent acceptance check back from the build.

@automation-ready is separate from the strategy: the generator applies it where it judges a scenario could be automated directly from the Gherkin, with no further interpretation needed.

Lever 3 — provenance tags

Every generated Feature: also carries three tags derived from the source requirement:

• @feature:<slug> — the feature the story was generated from
• @req:<REF> — the requirement reference, for traceability back to REQQA
• @priority:<level> — the requirement's priority

These are written into the generation prompt directly rather than drawn from the glossary, so they are consistent across all organisations and are not configurable from the UI. Treat them as the traceability spine: they are what lets a reader hold a scenario against the requirement it came from.

Reviewing AI-proposed tags

When the generator meets a situation the glossary doesn't cover, it is permitted to invent a tag — and it must define it when it does. Those inventions are saved against your organisation with a status of ai-proposed and appear in the AI-Proposed Tags box at the foot of the Tag Glossary, marked Pending Review.

For each proposal you can:

• Accept — opens the tag so you can revise the name, category, definition and usage before accepting. Accepting promotes it: the tag leaves the queue, joins your organisation's vocabulary, and is available to the next generation run. If you revise the name, the new name is re-checked for uniqueness — a rename can collide where the original did not, and a failed promotion leaves the proposal in the queue rather than losing it.
• Reject — deletes the proposal. The generator may propose the same name again on a later run.

This queue is the control point for vocabulary drift, and it repays regular attention. Left unreviewed, proposals accumulate and the AI reinvents near- duplicates of the same idea — audit alongside audit-trail, case-insensitive alongside case-sensitivity. Reviewing the queue after each significant generation run keeps the vocabulary tight.

note

Rejecting a proposal removes it from the glossary but does not strip the tag from any story already generated with it. Regenerate those stories if you want the tag gone from the Gherkin.

What the build receives

Stories reach a build agent through the release handover API, which returns each story's full Gherkin content — tags included, exactly as written. The tag definitions travel with them, as a companion to the domain-term glossary:

GET /api/v1/scopes/<scope_id>/tags

The response carries three things:

• tag_vocabulary — every tag that actually appears in the release's stories, with the definition, category and usage note in force for your organisation. Overrides are returned as your definitions, not the system defaults, and custom tags are included. A tag defined for your organisation but not used by this release is not returned — the vocabulary is scoped to what the release uses, exactly as the domain glossary is scoped to terms actually used.
• provenance_tags — @feature:, @req: and @priority:, reported separately as structural metadata rather than as vocabulary. They trace a scenario to its origin; they do not classify it.
• test_strategy — the letter code and a plain-language description, so the @test:* tags read as policy rather than as arbitrary labels. An application with no strategy recorded reports A, the same default the generator uses.

The same content appears in the exported release PDF, under Appendix B — Scenario tags, alongside the domain-term glossary. A consumer reading the PDF faces the same interpretation problem as an agent reading the API, and is owed the same answer.

Two details worth knowing:

• A tag in use but defined nowhere is still returned, with a null definition and defined: false. That is a real case rather than an edge case: deleting a custom tag, resetting an override or rejecting a proposal all leave already-generated Gherkin untouched, so a story can outlive the definition it was written under.
• The vocabulary is computed when you ask for it, not frozen. The copy a build agent receives is its own, and governs its build; ask again after changing a definition and you will get the new one.

note

Delivering the vocabulary is necessary but not sufficient. What a consuming agent does with @test:holdback is set by its own build instructions, which live outside REQQA. The handover now tells it what the tag means; it does not tell it what to do.

Result

Your organisation has a tag vocabulary whose definitions say what you mean by them, an application-level test strategy that decides which scenarios are mandatory, and a review queue that stops AI-invented tags accumulating unchecked. Stories generated from that point on carry tags a reader can act on — and the meaning of those tags travels with them, to the API and the PDF alike.

Related

• How to generate user stories — the generation loop the tags are produced by.
• Stories and features — the concepts behind scenarios, features, and the tag glossary.
• How to work with the glossary — the domain term dictionary, which is a separate vocabulary from scenario tags.
• The Dark Factory — how a release is handed to a build agent.