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 single 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. Your job is to read those findings and act on them: fix the requirement, accept what's right, set aside what isn't, and re-run until the requirement converges.
This page walks the full loop: run the analysers, watch the job complete, read the issues, and feed the fixes back in.
1. Open the Analyse tab
From any requirement, open it in reqView and switch to the Analyse tab (the URL
carries ?tab=analyze). The list view shows whether a requirement has already been analysed,
including which steps were run.
The Analyse 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 |
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.
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 prevents duplicate runs: while one analysis for this requirement is queued or running, you can't start another.
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 Analyse tab and the new issue counts will be there. For the full picture of how background work is scheduled, see Manual: Background jobs.
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. Read the issues
A finished analysis gives you a count of issues by severity on the Analyse tab. Click through to the full issue list — manageIssues — to work through them. Each issue carries:
- a severity — the analysers grade everything HIGH (shown as Critical), MEDIUM, or LOW;
- a confidence — HIGH (evidenced), MEDIUM (inferred), or LOW (speculative), so you can weigh how strongly REQQA stands behind it;
- a step code telling you which analyser raised it (e.g. an R-A issue is an ambiguity);
- a category — defect, suggestion, or scope query;
- a title, a description, and a recommendation for what to do about it.
Where to read them
- manageIssues — every issue for one analysis run, as cards or a list, filterable by severity, step, status, confidence and category. This is your main working surface.
- appIssues — a cross-artifact view: every active issue across the whole application, spanning the mission, requirements, and stories, paginated and filtered. Use it to see where the worst problems are concentrated before you dive into any single requirement.
- viewIssue — the detail page for one issue, where you can change its status or severity, assign it to a colleague, and add notes.
5. Act on each issue
Every issue has a status, and triaging an analysis means moving each issue to the right one:
| Status | Meaning |
|---|---|
| Open | New, not yet looked at |
| Accepted | A real issue you intend to fix |
| In Progress | Being worked on |
| Resolved | Fixed |
| Not An Issue | A false positive, or something you've decided not to act on |
| Superseded | Carried over from a run that's been replaced |
You can change a status from the issue cards, in bulk from the list view, or on the detail page.
Every status change requires a comment of at least 20 characters explaining why. This builds a durable audit trail on the issue, so anyone reading it later understands the decision — not just that it changed, but the reasoning. Changing an issue's severity likewise requires a note.
For R-D (Definitions) issues that flag an undefined term, you get two shortcuts on the issue: Accept Term adds the suggested term straight to your glossary and resolves the issue, and Reject Term adds it to the junk list so it won't be flagged again. See How to work with the glossary.
6. Feed the fixes back in
Reading issues is only half the loop. The point is to improve the requirement and re-analyse until the issue count falls. There are two routes:
Edit by hand. Open the requirement, rewrite the offending text guided by each issue's recommendation, save, and re-run the analysers. The convergence history on the Analyse tab will show the counts dropping run over run.
Synthesis (assisted). When an analysis has accumulated enough open issues (the default threshold is five; your organisation can change it), REQQA offers a Synthesis run. Synthesis reads the open issues together and proposes concrete edits to the requirement text — direct in-place edits, section additions, or advisory notes. You review each proposed change, accept or dismiss it, and accepting a change both rewrites the requirement (bumping its revision and writing a history record) and resolves the issues that drove it. See Manual: Synthesis and clean-up for how this works under the hood.
Either way, the cycle is the same: analyse → triage → improve → re-analyse, until the requirement is clean enough to build from.
Result
A requirement whose defects, ambiguities, and gaps have been surfaced, triaged with a documented rationale, and either fixed in the text or consciously set aside — and a convergence history that shows the quality improving with each pass.
Related
- How to manage your requirements — write and edit the requirements you'll analyse.
- Manual: The analysis engine — how DeFOSPAM and the analysers work conceptually.
- Manual: Synthesis and clean-up — turning issues into edits.
- FAQ: Analyser codes — the full list of step codes at a glance.