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.

caution

See Current limits below before relying on this. A new org tag that does not share its name with a system tag is not currently picked up by the generator.

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 in the editor so you can revise the name, category, definition, and usage before saving it into your organisation's vocabulary.
• Reject — deletes the proposal.

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.

It is worth being clear about what is not in that payload: the tag definitions are not. The handover glossary covers your domain terms — the dictionary definitions indexed against requirements and stories — and does not currently include the scenario-tag vocabulary. A build agent therefore sees @test:holdback on a scenario and must infer what to do about it.

In practice this means:

• Prefer the system tags for anything you expect a downstream reader to act on. Their names are self-describing and widely conventional.
• If your team relies on an override or a custom tag with non-obvious meaning, state that meaning in the build instructions you give the agent — do not assume the definition travels with the story.
• Treat the test strategy as the thing that carries real downstream weight: the @test:* distinction is the one most likely to be acted on.

Current limits

Three things behave less completely than the page suggests. They are known and under review; this section will be updated when they change.

1. Accepting an AI-proposed tag does not promote it. The Accept action saves your edits to the tag but leaves its status as ai-proposed, so the tag stays in the Pending Review list and does not join the vocabulary sent to the generator. Until this is resolved, the reliable way to adopt a proposed tag is to reject it and re-create it as an org tag with the same name — and, per point 2, to give it the name of an existing system tag if you need it to affect generation.
2. Only overrides of system tags reach the generator. The vocabulary sent to the AI is built from the system tag list with your overrides applied. An org tag whose name does not match a system tag is stored but is neither shown on the glossary page after creation nor included in the prompt.
3. Tag definitions do not travel to the build, as described above.

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 you know which of those tags carry their meaning downstream and which need explaining in the handover.

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.