How to analyse a requirement
When you'd do this: once a requirement has real content under its mission, and whenever you've edited it and want a fresh read on its quality before you generate stories or hand it to a build team.
Analysis is where REQQA earns its keep. You point the DeFOSPAM technique at a requirement, it runs one or more analysers against the text, and it returns a list of issues — defects, suggestions, and scope queries — each with a severity and a recommendation. This page covers running the analysers and reading what came back. Acting on what you find — triaging, synthesis, the bulk triage queue, and knowing when to stop — is a separate question, covered in How to manage analysis issues.
REQQA runs two independent analysis regimes against a requirement, on two separate tabs:
- Requirement Analysis — the eleven R-* analysers, run against this one requirement's own content in isolation (two of them, R-N and R-P, also use its parent chain and the application mission as context — see below).
- Tree Analysis — eight deterministic checks run against this requirement's whole descendant tree at once, looking for inconsistency between artefacts that no per-artefact analyser can see. See "Tree Analysis" below.
They're independent: neither blocks nor supersedes the other, and each has its own controls and its own results panel.
1. Open the Requirement Analysis tab
From any requirement, open it in reqView and switch to the Requirement Analysis tab
(the URL still carries ?tab=analyze, unchanged even though the tab's label was renamed from
"Analyse" once Tree Analysis needed its own tab alongside it). The tab shows you:
- the most recent analysis for this requirement, with its issue counts by severity;
- a convergence history — every prior run, side by side, so you can see issue counts falling as the requirement improves;
- the step picker for launching a new run.
If you're not sure which analysers to run, use Suggest Analyses. REQQA does a quick scan of the requirement and recommends the steps most likely to find something — a cheap way to focus an expensive run.
2. Choose your analysers (the R-codes)
REQQA analyses a requirement one step at a time. Each step is a focused analyser with a two-letter code; the requirement-level analysers are the R- family:
| Code | Analyser | Looks for |
|---|---|---|
| R-D | Definitions | Terms used but not defined in the glossary |
| R-G | Goals & Users | Whether the goal and the user/actor are clear |
| R-F | Features | Candidate features the requirement implies |
| R-I | Interfaces | External interfaces and integration points |
| R-R | Rules | Business rules and policy embedded in the text |
| R-E | Entities & Data | Data items and entities the requirement touches |
| R-C | Conditions & Decisions | Conditional logic and decision points |
| R-B | Boundaries | Limits, ranges, and edge values |
| R-Q | Quality Attributes | Performance, security, usability and other non-functionals |
| R-A | Ambiguity | Vague, subjective, or unmeasurable wording |
| R-M | Missing Elements | Things the requirement ought to state but doesn't |
| R-N | Necessity & Traceability | Whether the requirement traces to a parent or the mission |
| R-P | Appropriateness | Whether the requirement is pitched at the right level |
| R-W | Writing & Conformance | Escape clauses and other writing-quality problems |
Tick one or more steps and start the run. You don't have to run them all every time — a tight loop is often just R-A (Ambiguity) and R-M (Missing Elements) while you tighten the wording, with the broader steps reserved for a fuller pass.
Every step analyses this requirement's own content in isolation, except R-N and R-P, which also read the parent requirement chain and the application mission as context — R-N to judge whether the requirement traces to something real, R-P to judge whether it's pitched at the right altitude relative to its parent.
R-F (Features) is special. Once a requirement has active feature suggestions, R-F is locked — running it again would clash with what's already there. To re-derive features, use Reset & Regenerate Features instead, which clears the old set first. See How to generate stories and features.
3. Run it — and understand "queued" versus "running"
When you launch a run, REQQA does not analyse inline while you wait. It creates an analysis record at status queued and hands the work to a background worker. You'll see a flash like "Analysis #123 queued. Refresh the page to see progress." The analysers — which call the AI model and can take from seconds to several minutes depending on how many steps you chose — run off the request, so your browser never hangs.
The status moves queued → running → finished (or Partial if some steps completed and others failed). REQQA guards against duplicate and conflicting runs automatically: triggering a second run while one is already queued or running for this exact revision is rejected outright; if you've since edited the requirement, triggering a new run instead supersedes the old one in flight — it's stopped and marked Superseded, and your new run proceeds against the current content. You never end up with two runs racing each other for the same requirement.
Watch the Job Queue
To follow progress, open the Job Queue page rather than refreshing reqView repeatedly. It shows each background job's state and lets you confirm the analysis has finished. When it has, return to the Requirement Analysis tab and the new issue counts will be there. For the full picture of how background work is scheduled, see Manual: Background jobs.
When the Definitions step has many terms: batches and partial results
The Definitions step (R-D for a requirement, D-D for a story) asks the AI model to draft a suggested definition and impact statement for every undefined term it finds. A long or domain-heavy text can have hundreds of them, so REQQA sends them in batches of up to 25 terms, one batch after another, and makes the check that your defined terms are used consistently as one separate call. While it works, the status line on the Job Queue and the analysis panel shows where it is, for example R-D: batch 2 of 12. It never shows a count of terms.
If the AI model's answer to a batch cannot be read — it times out, returns an error, is cut off, or is missing something — REQQA sends that same batch once more, on its own, straight away. Nothing else is re-sent, and the results of every batch that worked are kept.
If the second attempt fails too, the step carries on with the next batch and the analysis finishes as Partial. Open it and look for these MEDIUM findings:
- drafting_failed — names the batch and lists its terms. Those terms are still undefined but have no suggested definition. The same finding appears if the model answered a batch but left some of its terms out.
- consistency_not_judged — the consistency check failed, so usage of your defined terms was not compared with their definitions this time.
The analysis summary also says that some terms were not drafted or judged, and the readiness verdict is never READY for a partial result. To fill the gaps, analyse again, or define the listed terms directly in the glossary.
If three batches in a row fail, REQQA stops sending further batches — the AI service is evidently unavailable — and reports the terms of every unsent batch the same way. If every call the step made failed, the step fails and reports no findings; the analysis is then Partial if other steps completed, or failed if it was the only step.
Cancelling a run
Started a run you didn't mean to, picked the wrong steps, or just want to stop and rethink? A Cancel button sits next to the run both on the Requirement Analysis tab (while it's queued or running) and on the Job Queue page — click it, confirm, and the job is stopped immediately: dequeued if it hadn't started yet, or signalled to halt mid-step if it had. Any issues the run had already written are marked Superseded at the same time, so nothing half- finished is left behind for you to clean up by hand.
If more than one analysis is active for the same requirement at once (this shouldn't normally happen, but can if you triggered a bulk run and an individual one in quick succession), the Job Queue page shows a Cancel All action scoped to that requirement, so you don't have to stop each one individually.
A cancelled run shows up afterwards in the Job Queue's Recent list with status Cancelled — distinct from Superseded, which is what you'll see instead when REQQA stopped a run automatically because you triggered a newer one, rather than you stopping it yourself.
Re-running analysis supersedes the previous run. Any issues from the old run that were still Open or Accepted are marked Superseded — they don't disappear, but they drop out of the active list. REQQA warns you before re-running if you still have unresolved issues, so you don't accidentally bury work in progress.
4. Tree Analysis — checking the whole tree, not just this requirement
Every check above looks at one artefact. A requirement can pass all eleven cleanly while still contradicting its own children, its siblings, or the stories written against it — nothing in the Requirement Analysis tab ever compares them. Tree Analysis is the second regime for exactly that gap: eight deterministic checks (no AI model call) run against this requirement's entire descendant tree at once —
- feature coverage, rule-to-scenario and scenario-to-rule tracing, hierarchy completeness, and rule inheritance (structural checks, five of the eight); and
- terminology and definitions consistency across the tree, including drift between a parent and its direct children (three checks, reusing the same glossary matcher R-D and D-D use).
Switch to the Tree Analysis tab to run it. If the tab shows "Tree termindex is stale", click Rebuild Tree Termindex first — the tree-wide term index that these checks read isn't rebuilt automatically (there's no scheduler), so a requirement edited since the last build needs an explicit rebuild before the terminology checks can run. Once current, Run Tree Analysis queues the run the same way a per-artefact run does, and the tab gets its own results panel — severity breakdown, readiness, and a summary — separate from the Requirement Analysis tab's.
Tree-level findings land in the same issue list as everything else, filterable by artifact type "Requirement Tree" on the app-wide issue list, and are disposed of through the exact same accept / reject / status-change actions as any other finding.
Result
A requirement whose own content, and its consistency with the rest of its tree, have been surfaced by analysis and are ready to be read and acted on — see How to manage analysis issues for that half of the loop.
Related
- How to manage analysis issues — reading, triaging, and resolving what analysis finds.
- How to monitor and cancel background jobs — the Job Queue page, Cancel All across multiple active analyses, and how Cancelled differs from Superseded.
- How to manage your requirements — write and edit the requirements you'll analyse.
- Manual: The analysis engine — how DeFOSPAM and the analysers work conceptually.
- FAQ: Analyser codes — the full list of step codes at a glance.