Skip to main content

Stories and Features

In REQQA, a requirement says what the system must do. A feature is a discrete capability that a requirement promises, and a story is a concrete, testable description of how that capability behaves — usually written in Gherkin. Features and stories sit one level below requirements in the hierarchy and inherit their context: the mission at the top, the requirement and its ancestors above, and the glossary alongside.

This page explains the model — what features are, how stories are generated from them, what surrounds a story (glossary terms, versions, history), and how REQQA tracks whether a story has drifted out of step with the requirement it came from.

Features​

A feature is a named capability derived from a requirement. Features are not free-text notes; each one is a record in the feature_suggestions table, tied to a requirement (reqid) and an application (appid), with a feature_name, supporting requirements_text, a status (active or rejected), and an origin.

Where features come from​

Most features are proposed by the analysis engine. When you run the DeFOSPAM Features Analysis step (analyser code R-F) against a requirement, REQQA reads the requirement and proposes the features it implies. Each proposal is written to feature_suggestions with origin='ai' and status='active'. You then curate them on the Feature Suggestions page: keep the ones that are real (Accept, leaving them active) and discard the ones that are not (Reject, setting them rejected). You can also add your own — a manually created feature carries origin='manual' — to split one AI feature into two, merge several into one, or capture something the analysis missed.

note

R-F is one of REQQA's functional-only analysis steps. It is meaningful only for requirements that describe behaviour a user can exercise. See The analysis engine for the full set of DeFOSPAM steps.

The has-features flag​

Not every requirement yields features. A constraint ("data must be retained for seven years"), a quality attribute, or a pure policy statement describes the system without naming a capability you would write a story for. Each requirement therefore carries a Has Features flag (requirements.has_features, default true).

When you mark a requirement as not having features:

  • The R-F step is skipped entirely for that requirement during analysis — there is nothing to extract, so REQQA does not spend tokens trying.
  • That requirement is excluded from story generation: with no features, there is nothing to generate stories from.

Setting the flag honestly keeps your feature list and story backlog focused on the requirements that genuinely describe user-facing behaviour.

Stories​

A story is a record in the stories table. It has a title, content (the Gherkin body), a parent requirement (reqid), the owning application (appid), a revision number, and two fields that track its lineage: source_feature_id (the feature it was generated from, if any) and origin (how it came to exist).

Stories in REQQA are written in Gherkin — the Feature: / Scenario: / Given / When / Then structure familiar from behaviour-driven development. When you save a story, REQQA validates the Gherkin: it derives the story title from the Feature: line automatically, and it surfaces any syntax problems as warnings. Validation is warn-and-allow — a story with imperfect Gherkin still saves, but you see the line numbers and messages so you can fix them. Story titles must be unique within an application; REQQA rejects a duplicate title on manual save.

Scenario tags​

Gherkin scenarios can carry tags (for example @test:required, @risk:high). REQQA maintains a tag glossary of system tags (shared across all organisations), org tags (your own definitions and overrides), and ai-proposed tags that story generation suggests. The tags group along categories such as scenario purpose, test characteristic, data condition, risk, and test strategy, and they let your stories carry consistent, defined metadata rather than ad-hoc labels.

Generating stories from features​

REQQA can write the first draft of your Gherkin stories for you. Story generation — internally codenamed STORYTELLER — takes a requirement's active features and produces one story per feature.

Entry criteria​

Before generation runs, REQQA checks the requirement is ready. Some criteria are blocking (generation cannot proceed) and some are warnings (you see them and decide):

  • At least one active feature must exist — blocking. With no features there is nothing to generate, so run R-F analysis first.
  • The requirement must have substantive content — blocking below roughly 50 characters.
  • The requirement should have been analysed — warning if it has not; generated stories may need rework.
  • There should be no open high- or medium-severity issues on the requirement — warning, with a count, if there are.
  • The requirement should be indexed for glossary terms — warning if its term index is empty, because indexed terms feed the generator (see below).

What goes into a generated story​

For each feature, REQQA assembles a rich context for the AI: the requirement's own content, the ancestor chain of parent requirements above it (so inherited rules are honoured), the glossary terms relevant to the requirement and its ancestors with their definitions, and the tag glossary so generated scenarios use defined tags. The result is a Gherkin story that is validated before it is saved. If the generated title clashes with an existing story, REQQA appends a numeric suffix to keep titles unique.

Generation runs as a background job — a single feature, all active features of one requirement, or all eligible requirements across the application in one bulk run. Re-running generation for a feature that already has a story updates that story in place (bumping its revision and writing a history row) rather than creating a duplicate, because REQQA matches on source_feature_id.

For the step-by-step procedure, see How to generate stories.

Glossary terms per story​

Every story shows which of your defined glossary terms appear in it. REQQA scans the story's title and content against the organisation's defined terms and records each match in the termindex table. The Glossary Terms page for a story then lists those terms with their definitions, so a reader can see exactly which domain vocabulary the story depends on — and spot terms that are used but not yet defined.

This index is not magic: it reflects the currently defined terms. If you add or change a definition, re-index the story (a single story, or all stories in the application at once) to bring its term list up to date. See The glossary for how definitions are built and maintained, and How to work with the glossary for the indexing controls.

Versioning and history​

Stories are versioned. Every save — whether you edit a story by hand or regenerate it — increments the story's revision and writes a snapshot to the stories_history table. Each history row records the action (Create or Update), the editor, the timestamp, and the full content as it stood after that change.

From a story you can open its History to see every revision in order, view any past version, and produce an inline delta between two versions to see exactly what changed in the Gherkin. This audit trail matters because stories are generated artefacts that get revised repeatedly as requirements settle — the history is your record of how the behaviour specification evolved.

Staleness: when a story falls behind its requirement​

A generated story is only as current as the requirement it came from. If you change the requirement after the story was written, the story may no longer describe the intended behaviour. REQQA detects this automatically.

A story is stale when its parent requirement was updated more recently than the story itself — that is, when requirement.updated > story.updated. The story list and the story view both flag stale stories so you can see, at a glance, which stories need attention after a requirement change. Staleness is derived on the fly from the two timestamps; it is not a stored status, so it always reflects the current state.

The origin field and regeneration​

Detecting staleness is only half the story; the other half is knowing whether it is safe to regenerate. That is what the story's origin field is for. A story's origin records how it came to exist:

  • generated — produced by story generation from a feature. Safe to regenerate: the generator wrote it, so the generator can rewrite it.
  • manual — authored or edited by a person (the default for a story you create yourself). Regenerating would destroy human work, so it needs explicit confirmation.
  • imported — brought in from an external source.

This distinction lets REQQA offer the right action when stories go stale: refresh the generated stories freely, but treat manual stories with care. The origin field is the guard rail that keeps automated regeneration from silently overwriting work a person deliberately wrote.

caution

Origin is what separates "safe to overwrite" from "human-authored". Before bulk regenerating stale stories, check their origin — a manual story may contain refinements that were never captured back in the requirement or its features.