Skip to main content

How to manage analysis issues

When you'd do this: right after any analysis run — per-artefact or tree-level — once there's a list of issues waiting for a decision.

Running analysis is only half the loop (see How to analyse a requirement). This page covers the other half: reading what came back, deciding what to do with each finding, and the three routes REQQA offers for actually resolving it — by hand, via synthesis, or via the bulk triage queue.

Where issues live​

  • 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 for a single run.
  • appIssues — a cross-artifact view: every active issue across the whole application, spanning the mission, requirements, stories, and requirement trees, paginated and filtered. Use it to see where the worst problems are concentrated before diving into any one requirement.
  • viewIssue — the detail page for one issue: change its status or severity, assign it to a colleague, add notes, and (for a story-linked issue) edit the story inline.

Statuses, and the audit-trail rule​

Every issue has a status, and triaging an analysis means moving each one to the right one:

StatusMeaning
OpenNew, not yet looked at
AcceptedA real issue you intend to fix
In ProgressBeing worked on
ResolvedFixed
Not An IssueA false positive, or something you've decided not to act on
Absorbed RiskAccepted as a known, named risk rather than fixed
SupersededCarried 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.

note

Every status change requires a comment of at least 20 characters explaining why — with no exceptions, including the quick Accept button on an issue card. This builds a durable audit trail: anyone reading it later understands 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, two shortcuts sit 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.

Three ways to actually resolve issues​

Edit by hand. Open the requirement or story, rewrite the offending text guided by each issue's recommendation, save, and re-run the analysers. The convergence history on the Requirement Analysis tab shows the counts dropping run over run. This is the only route for a change too small or too specific for the other two to be worth setting up.

Synthesis (assisted, one requirement at a time). Once an analysis has accumulated enough open issues (five by default; your organisation can change it), REQQA offers a Synthesis run from synthResults. Synthesis reads the open issues together and proposes concrete edits — direct in-place edits, section additions, or advisory notes — each covering one or more issues. You review each proposed change and Accept or Dismiss it; accepting both rewrites the requirement (bumping its revision, writing a history record) and resolves every issue the group covers.

  • Manual review. A proposed direct edit is presented for manual review, instead of being offered for a one-click Accept, whenever REQQA can't safely locate what it's supposed to replace in the requirement's current text. That happens two ways: the content genuinely moved on since the run started (someone edited it in between), or the AI's quoted "before" text simply never matched what's actually there — a mis-quote, not a timing race. Either way REQQA won't guess; it shows you the contributing issues and the current section text so you can make the edit by hand.
  • Bulk accept/dismiss. When several groups need the same disposition — most often several direct_edit groups each fixing a different sentence in the same section, since a single group can only ever quote one contiguous span — select them with the checkboxes and use Accept Selected / Dismiss Selected instead of clicking through one at a time. Under the hood each group is still applied individually and in order, exactly as if you'd clicked each one yourself; this only saves the clicks.
  • See Manual: Synthesis and clean-up for how synthesis works under the hood, including the section-merge rules that keep placeholder-type proposals from piling up as duplicates.

Triage Queue (bulk, across many issues at once, AI-assisted per item). Where synthesis rewrites content to clear a cluster of issues on one requirement, the Triage Queue proposes a disposition for issues one at a time, without editing anything — reached from Manage Issues via a Triage These action. It exists for the volume case synthesis doesn't reach: hundreds of similar low-effort findings (typically R-D "undefined term" noise) spread across many artefacts, not five-plus issues clustered on one requirement.

  • Scope it first. The scope selector defaults to just the artefact you triaged from — not every open issue in the application. Switch it explicitly to "All open issues in this application" (optionally narrowed by analysis step) for the wider sweep; that default exists because the naive "everything" scope was genuinely overwhelming at REQQA's own volume (5,000+ open issues at one point).
  • Per item, you get an AI-suggested disposition and rationale, generated fresh the first time you reach that item — expect a several-second wait per new item, that's a real AI call, logged to the AI log like any other analysis call, not a stall.
  • Confirm writes the AI's suggested disposition through the exact same disposition path as a manual Accept, with the AI's rationale as the note. Override lets you pick a different disposition with your own rationale instead (the same 20-character rule applies, and the same note-template dropdown is available). Skip leaves the issue untouched for a later session — it isn't a disposition of any kind.
  • A session summary at the end reports how many were confirmed as-suggested versus overridden, which is the running measure of how much you can trust the AI's suggestions for that kind of finding.

Knowing when to stop​

Not every open issue is worth individually triaging, and treating "issue count" as a target to zero out is the wrong instinct. In particular: a technical, code-referencing requirement will always generate a large volume of LOW-severity R-D "undefined term" findings — function and table names, status enum values, and process jargon coined within the requirement itself. None of those live in the org glossary, and most of them shouldn't: a code identifier defines itself by existing in the codebase, it doesn't need a business-glossary entry. This is sometimes called the R-D glossary treadmill — defining one batch of terms routinely surfaces the next batch of newly-coined compounds built on them, not because the requirement is getting worse, but because R-D is doing exactly what it's for.

A practical stopping rule: triage every HIGH severity issue individually — there are usually few enough that this is cheap, and severity means REQQA thinks the finding matters. For the LOW-severity R-D pile, look for the handful that are genuinely the feature's own core domain nouns (worth a real glossary entry) versus the majority that are incidental code symbols or enum values (not worth one), and leave the rest. Chasing every LOW finding to zero on a long technical requirement is busywork, not quality improvement.

Result​

Every issue from a run has either been fixed, formally accepted as a risk, or dismissed with a documented reason — and the ones left genuinely open are the ones actually worth someone's attention next.