Skip to main content

Requirements

A requirement is the central object in REQQA. Everything else — the analysis you run, the stories you generate, the glossary terms you reference — orbits the requirement. This chapter explains how REQQA models a requirement: the fields it carries, the structure that shapes its content, how it is versioned and audited, how requirements form a hierarchy, and the single, deliberate path by which requirements are written.

If the mission is the top of your hierarchy, requirements are the body of it. Each one inherits the mission's context, and each one is a candidate for analysis under the DeFOSPAM technique.

What a requirement is made of​

Every requirement belongs to one application (the appid field) and carries a small set of identifying and classifying fields alongside its body content.

Reference code (ref)​

The reference is the human-facing identifier you give the requirement — for example FR-20, NFR-03, or TR-02. It is a free-text string (up to 30 characters), so REQQA does not impose a numbering scheme on you; you choose the convention that suits your project. References are how you and your team talk about a requirement, and how parent/child relationships are expressed when importing or writing through the API (a child can name its parent by parent_ref).

Type​

REQQA does not store "type" as a separate enumerated field — the type is conventionally encoded in the reference prefix. The references in the working system follow the familiar pattern:

  • FR — a functional requirement: something the system must do.
  • NFR — a non-functional requirement: a quality the system must have (performance, availability, usability, security).
  • TR — a technical requirement or constraint: a mandated technology, interface, or data format the solution must respect.
note

Because the type lives in the reference prefix rather than a constrained field, REQQA stays flexible about your taxonomy. Use whatever prefixes your organisation already uses — the prefix is purely a naming convention, not a hard-coded category.

Priority​

Each requirement has a priority (priorityid), chosen from the organisation's priority list. The standard set, in sequence order, is:

PriorityMeaning
HighHighest priority
MediumMedium priority
LowLow priority
Non Req.Not a requirement
WithdrawnWithdrawn requirement

The last two are doing real work: Non Req. lets you keep a record that has turned out not to be a requirement without deleting it, and Withdrawn marks something that was once in scope but has since been dropped — preserving the history rather than erasing it.

The body (content)​

The substance of the requirement lives in the content field — a Markdown-formatted text body (up to 64,000 characters). This is what the analysis engine reads, what synthesis rewrites, and what the title is derived from. A requirement is only as good as its content: a one-line body gives the analysers little to find fault with, whereas a structured, complete body lets DeFOSPAM do meaningful work.

Title (derived, not typed)​

You generally do not type the title by hand. REQQA derives the title from the first Markdown heading in the content body. The deriver scans the content line by line and takes the first heading it finds — #, ##, ### or #### — stripping the hashes. If the content has no heading at all, REQQA stores a placeholder title flagged as "no title found" so the gap is visible rather than silent.

tip

Always start your requirement content with a heading line, for example # Order cancellation. That single line becomes the requirement's title everywhere it is listed, so a clear heading keeps your requirements list readable.

Other fields​

  • Notes (req_notes) — your private working notes on the requirement, separate from the body.
  • Source URL (urlsource) — an optional link to where the requirement originated (a ticket, a standard, a stakeholder document).
  • Has features (has_features) — whether this requirement is one from which stories and features should be generated.
  • Assigned to (assignedid) — the user responsible for the requirement.
  • Recommended analyses — the analyser codes REQQA suggests running against this requirement (see the analysis engine).

Requirement templates​

A requirement template is a reusable content structure that shapes what a requirement should say. Rather than starting from a blank box, you choose a template and fill in its sections — much as the mission guideline shapes the mission.

A template carries a name, a Markdown content skeleton (the headings and prompts a requirement of this kind should contain), optional tags, and its own list of recommended analyses. Templates belong to an organisation and may be scoped to a specific application.

Templates are not cosmetic. When you create a requirement through the UI or the API, a template_id is required — the system will not let you save a requirement that is not associated with a template. This guarantees that every requirement in the system was written against a known structure, which in turn makes the requirements analysable and comparable. When you change a requirement's template, REQQA can re-evaluate it against the new structure; on edit, a template may also be removed entirely if the requirement no longer needs one.

note

The template choice influences which analysers REQQA recommends, because different kinds of requirement warrant different checks. A non-functional requirement template, for instance, will recommend a different analysis mix from a functional one.

Versioning and the audit trail​

Requirements are versioned. Each requirement carries a revision number that increments as the record changes, and the created/created_by and updated/updated_by fields record who touched it and when.

The full lineage lives in a companion table, requirements_history. Every time a requirement is created or changed, a history row is written that is a complete post-update snapshot of the requirement — all of its field values as they stood after the change, plus three extra fields:

  • action — what kind of change it was. The vocabulary is Create, Update, Cleanup, and Reformat.
  • recid — a back-reference to the live requirement.
  • changenotes — a short note describing the reason for the change.

Because each history row mirrors the full state of the requirement at a given revision, the history table alone is enough to reconstruct what a requirement looked like at any point in its life — you never have to consult the live record to rebuild a past state. A Create row matches the requirement at revision 0; each subsequent Update, Cleanup, or Reformat row matches the requirement at the revision it produced.

caution

Cleanup and Reformat denote non-semantic edits — tidying whitespace, reformatting Markdown, normalising headings — as distinct from an Update, which changes what the requirement means. Keeping these separate lets you tell substantive change from housekeeping when you read the audit trail.

Parent and child requirements​

Requirements form a hierarchy. Each requirement has a parentid (the requirement it sits under, or 0 for a top-level requirement) and a parentseq (its position among its siblings). This lets you decompose a large requirement into children — for example FR-20 with children FR-20.1, FR-20.2, and so on, and grandchildren below those.

The hierarchy is more than presentation. Decomposition is a deliberate technique in REQQA: breaking a broad requirement into focused children tends to surface issues that a single monolithic requirement hides, because each child can be analysed in its own right. When you write requirements through the API, a child can declare its parent by reference (parent_ref) and REQQA resolves the link and computes the sequence for you.

Personas​

A persona describes a class of user — a name and a rich description of who they are, what they are trying to achieve, and the context they bring. A requirement can be associated with a persona (personaid) so that its context includes who the requirement is for.

Personas matter most downstream: when REQQA generates stories from a requirement, the persona shapes the voice and the goals of those stories, and when it analyses a requirement, the persona is part of the context the analyser reasons over. Personas are defined per organisation and reused across requirements.

The origin field​

Every requirement records its origin — where it came from. This is a first-class field precisely so that requirements of different provenance can be filtered, reported on, and treated differently. The origin values in use include:

  • manual — written by a person in the UI.
  • mission-generated — produced by REQQA from the application's mission.
  • demo-generated — created as part of a demonstration application.
  • training-generated — produced during training or experimentation.
  • csv-import, csv-import-grouped, csv-import-consolidated — brought in via requirement import, with the variants recording how the import was grouped.
  • retro-placeholder — a deliberately thin requirement that anchors functionality which already ships in production but has not yet been documented to full standard. It marks a retrofit backlog rather than a hypothetical future feature, and consumers typically exclude it by default.
tip

The requirements list lets you filter by origin. Filtering to manual and mission-generated shows your authored corpus; filtering to retro-placeholder shows the documentation debt waiting to be paid down.

How requirements are written​

There is one rule that governs all requirement writes, and it is worth stating plainly: requirements are written only through REQQA's UI and its requirements API — never by editing the database directly.

The reason is that a great deal happens server-side on every write, and bypassing it produces silent inconsistency:

  • Title derivation runs from the content, so the stored title and the content's heading always agree.
  • A history row is written automatically after every change, keeping the audit trail complete.
  • Validation enforces the rules — a template must be present, references and titles must be unique within the application, and a child's parent is resolved and sequenced.
  • The revision is bumped and created_by/updated_by are set from the authenticated user.

The API surface for this is POST /api/v1/requirements to create a requirement and PUT /api/v1/requirements/<id> to update one. Both run the same central create/update logic and the same history writer that the UI uses, so however a requirement enters the system — typed in a form, imported from a file, or written by a tool — it is created consistently and audited the same way.

caution

Direct SQL writes to requirements or requirements_history are not permitted, even for bulk operations. A batch import should loop over API calls, not reach into the tables, precisely so that title derivation, history, and validation are never skipped. If a genuine need cannot be expressed through the API, the answer is to extend the API — not to side-step it.