Skip to main content

How to generate user stories

When you'd do this: once a requirement carries features and you want concrete, testable Gherkin user stories to sit beneath it — ready to review, analyse, and feed into the build.

In REQQA, a user story is a Gherkin feature (a Feature: with one or more Scenario: blocks) that belongs to exactly one requirement. You rarely write stories from scratch. Instead, REQQA generates them from the features the analysis engine has already identified on a requirement, drawing on the requirement's content, its ancestor requirements, the application mission, and any glossary terms indexed against it.

This page covers the whole loop: confirming a requirement is ready, generating stories (for many requirements at once, or one requirement at a time), watching the background jobs run, reviewing the results, and regenerating when a requirement changes underneath its stories.

Before you start: requirements need features​

Story generation reads from a requirement's active features, so the single hard prerequisite is that the requirement has features. Features come from the R-F (Functions) step of the analysis engine: running R-F on a requirement produces feature suggestions, which you accept to make them active.

A requirement also carries a Has Features (HF) flag. When that flag is off, REQQA treats the requirement as one that legitimately produces no functions (a heading, a constraint, a non-functional statement) and shows its R-F column as N/A on the requirements list. Such a requirement will be skipped by story generation. So the readiness checklist is:

  1. The requirement has its Has Features flag on.
  2. R-F has been run and at least one feature suggestion has been accepted (so it is active — pending and rejected suggestions do not count).
  3. The requirement has substantive content (very short requirements are blocked).
tip

Use the Has Features filter on the requirements list (set it to Yes) to see only the requirements that are candidates for story generation.

Option A — generate for many requirements at once (bulk)​

This is the fastest way to turn a whole tranche of analysed requirements into stories.

  1. Open Requirements from the navigation to reach the requirements list.
  2. Tick the checkbox beside each requirement you want stories for. (The header checkbox selects all rows currently shown, so combine it with the filters to scope your selection.)
  3. Click Generate Stories in the action bar at the top.
  4. Confirm the prompt. REQQA queues one background generation job per eligible requirement.

Not every selected requirement will be queued. REQQA silently skips a requirement and tells you why in the summary:

  • No features — the requirement has no active features to work from.
  • Criteria not met — a blocking entry criterion failed (for example, content too short).
  • Already running — a generation job for that requirement is already queued or running.

The confirmation reports how many jobs were queued and how many were skipped in each category, then points you to the Job Queue.

note

Bulk generation only ever queues work — it does not generate inline. Each job runs in the background, so a large selection will not block your browser.

Option B — generate for a single requirement​

When you want to see the entry criteria up front, or generate one feature at a time, work from the requirement's own generation page.

  1. From the requirements list (or the requirement view), open Generate Stories for that requirement. This is the generateStories page for the requirement.
  2. REQQA shows an entry-criteria panel. Some criteria are blocking (you cannot proceed until they pass), some are warnings (you see them and decide), and some are informational:
    • Blocking: the requirement must have at least one active feature, and must have substantive content.
    • Warning: the requirement has never been analysed; or it has open high- or medium-severity issues; or its glossary terms have not been indexed (offer to re-index so terms are available to the generator).
  3. Below the criteria, REQQA lists the features that will each become a story, with each feature's origin (AI or Manual) and any existing story already attached to it.
  4. Click Generate All Stories to queue every feature, or use the per-row Generate button to do one feature. Where a feature already has a story, the per-row button reads Regenerate instead — generating again replaces the existing story with a new revision rather than creating a duplicate.

One feature produces one story. The generated story's title is derived from the Feature: line of the Gherkin, and the story is marked with origin generated (see Staleness and regeneration below).

Watching the queue​

Generation runs as background jobs, the same machinery described in Background jobs. After queuing you can:

  • Open the Job Queue page to watch jobs move through queued → running → finished. This is the recommended way to monitor progress.
  • Stay on the single-requirement Generate Stories page — it polls for progress and updates in place while a generation job for that requirement is running, and shows the last completed run when it finishes.

A single feature is quick; a requirement with many features, or a bulk run across many requirements, will take proportionally longer as the jobs work through the queue.

Reviewing the results​

Generated stories appear in two places.

The stories list. Open Stories from the navigation. Stories are grouped under their parent requirement, so you can see at a glance which requirements now have coverage and which do not. Each row shows whether the story has been analysed, and flags any stale stories (see below). You can filter the list to a single requirement.

The story view. Click a story to open View Story, the tabbed view-and-analyse page:

  • The View tab shows the Gherkin content and the parent requirement it belongs to.
  • The Analyse tab lets you run DeFOSPAM analysis on the story itself — generation gets you a first draft; analysis then finds faults in the Gherkin (ambiguity, missing scenarios, untestable steps) just as it does for requirements. Select the steps you want and run them; the page reports issue counts by severity once the analysis finishes.
tip

Generation produces a starting point, not a finished artefact. Treat every generated story as a draft to read, analyse, and edit. You can edit a story by hand at any time — REQQA validates the Gherkin syntax on save and warns you about problems without blocking the save.

Glossary terms in a story​

Every story is indexed against your glossary. From a story you can open its Glossary Terms page to see which defined terms appear in the story and their definitions — a quick way to confirm the story uses your domain vocabulary consistently. If you edit a story, re-index it (or use Re-Index All Terms on the stories list) so the term index stays current.

Staleness and regeneration​

A story is a snapshot of its requirement at the moment it was generated. When you later edit the requirement, its stories become stale — REQQA derives this by comparing the requirement's last-updated time against the story's. Stale stories are flagged on the stories list and on the story view so you know they may no longer reflect the requirement.

Regeneration is origin-aware, which protects work you authored by hand:

  • Stories REQQA generated carry origin generated and are safe to regenerate — doing so replaces them with a fresh revision.
  • Stories you wrote yourself carry origin manual. Regenerating one overwrites your authored content, so REQQA treats manual stories with more care.

To refresh stale generated stories, return to the requirement's Generate Stories page and regenerate the affected features — each regeneration bumps the story's revision, and the old version is kept in the story's history so nothing is lost.

caution

Re-running analysis or regenerating does not delete history. Previous story revisions remain viewable, and re-running a story analysis supersedes the earlier analysis rather than erasing it.

Result​

Each feature-bearing requirement now has one or more Gherkin user stories beneath it, visible on the stories list grouped by requirement, each ready to be reviewed, analysed for faults, and edited. Requirements without features are left untouched, and any story whose requirement has since changed is flagged as stale so you know to regenerate or review it.