Skip to main content

Synthesis and Cleanup

Analysis is only half the loop. Once REQQA has analysed a requirement and surfaced a list of issues, those findings need to make their way back into the requirement's content — otherwise the analysis is just a report that nobody acts on. Synthesis and cleanup are the two mechanisms that close that loop. Synthesis turns analysis issues into concrete, reviewable content changes; cleanup keeps the resulting text well-formed as it accumulates edits over many cycles.

This page explains how both work, why they exist, and how they fit into the wider pipeline that runs from a mission down through requirements, analysis, and on to stories.

Where synthesis sits in the pipeline​

REQQA's processing stages each have an internal codename. They are not visible in the interface, but they are a useful way to talk about who does what:

CodenameWhat it does
COMPOSERGenerates draft requirements from your mission statement.
SPLITTERDecomposes an over-large requirement into focused children (planned).
SYNTHESISERReads the open analysis issues and proposes content changes that resolve them.
UNSCRAMBLERMechanical and AI-assisted content cleanup — duplicate sections, escaped characters, stray placeholders, section reformatting.
DEDUPERCollapses near-duplicate analysis issues before synthesis (planned).

The natural order is: compose, edit, optionally split, analyse, then synthesise the fixes, and clean up the result. You stay in control at every hand-off — nothing is applied to a requirement until you accept it.

note

These codenames describe stages of the same workflow, not separate products. When the documentation refers to "the synthesiser" it means the synthesis run described below; "the unscrambler" means the Clean Up tab tooling.

The synthesis loop​

Synthesis is available only for requirement analyses (not story analyses). After an analysis has produced issues, REQQA shows a synthesis control on the issues view once enough actionable issues exist — the threshold is the application's synthesis minimum issues setting (five by default). Below that threshold there is little to gain from a synthesis pass, so the control stays hidden.

When you start a run, REQQA:

  1. Creates a synthesis run record (status pending) tied to the analysis and its requirement, and supersedes any earlier runs for the same requirement so you are never looking at stale proposals.
  2. Enqueues a background job (the SYNTHESISER). The job reads the requirement's content, the matching requirement template, and the set of open issues, then asks the configured AI model to group related issues into a small number of coherent change proposals rather than one edit per issue.
  3. Stores the proposals as synthesis groups, each linked back to the issues it resolves, and marks the run finished.

The job runs asynchronously, so the page polls a status endpoint while it works and then takes you to the results.

The results page​

The synthesis results page (synthResults) lists every proposed group, ordered by a priority score the model assigns, so the highest-value changes sit at the top. Each group has a change type that tells you what kind of action it represents:

  • Direct edit — a concrete before/after change to a specific section. REQQA computes a word-level diff between the current section text and the proposed replacement so you can see exactly what would change.
  • Placeholder — a proposal to fill a gap where the requirement is silent (for example, an acceptance criterion that analysis found missing).
  • Advisory — guidance that cannot be applied mechanically; you act on it by editing the requirement yourself.

Each group shows the issues it would resolve, so you can judge a proposal against the findings that prompted it. A summary at the top counts the totals for each type and status (pending, accepted, dismissed).

caution

Where several pending groups target the same section, REQQA flags it as a shared section so you know what you're looking at — it's informational, not a warning to accept at most one. Placeholder groups landing in the same section are pre-merged into a single group before you ever see them (below), and multiple direct edit groups in one section are each applied independently and safely, in the order you accept them. The one thing that can still happen is one edit's expected "before" text no longer matching after an earlier edit in the same batch changed the surrounding text — REQQA refuses that specific accept with a clear error rather than guessing (see manual review, below); it never silently corrupts the content either way.

Accepting, dismissing, bulk actions, and manual review​

For each group you can:

  • Accept — REQQA applies the proposed change to the requirement's content, bumps the requirement revision, writes a requirements_history snapshot (action Update), and resolves every issue linked to the group (their status becomes Resolved with a note recording that they were resolved via synthesis). Acceptance is recorded against the specific history version it produced.
  • Dismiss — the proposal is discarded; the underlying issues stay open for you to handle another way.
  • Accept Selected / Dismiss Selected — select several pending groups with the checkboxes and apply the same disposition to all of them in one action. This is most useful when a section has fragmented into several direct_edit groups, one per sentence changed (a single group can only ever quote one contiguous span, so that fragmentation is expected, not a bug). Each selected group is still accepted or dismissed individually and in order — this only saves the clicks, it doesn't change what happens underneath.

Placeholder groups (proposals that add new content rather than replace existing text — they carry no "before" text to quote) are automatically merged by section before you ever see the results page: if the model proposed several separate placeholder additions for the same section, REQQA combines them into one group with one concatenated proposed change. This is done server-side regardless of what the model returns, because relying on the model to consolidate them itself proved unreliable at volume (a single section producing nine or more separate placeholder proposals, more than once, in practice).

Manual review is what you get instead of a one-click Accept when REQQA can't safely locate a direct_edit proposal's quoted "before" text in the requirement's current content. Two different things can cause that, and both are shown the same way — the contributing issues and the current section text, so you can make the edit by hand:

  • the content genuinely changed after the run started (someone edited it in the meantime), or
  • the AI's quoted text never matched what's actually there in the first place — a mis-quote, not a timing issue.

Either way, REQQA does not guess at where an unmatched edit belongs. A proposal that quotes an unusually large share of its target section — even one that does match exactly — is refused for the same reason: replacing most of a section with something short and unrelated is exactly the kind of edit that shouldn't be applied automatically just because the text happened to match.

The net effect of one synthesis pass is that a cluster of open issues becomes a short, prioritised list of reviewable edits, and accepting them both improves the requirement and clears the corresponding findings in a single action.

The Clean Up tab​

Repeated analyse-synthesise cycles keep a requirement correct, but they can leave its text untidy: duplicate headings creep in, escaped characters (\n, \t) survive a paste, template prompts get left behind, and sections grow unbalanced. The Clean Up tab on the requirement view is where the UNSCRAMBLER addresses this. It works in two modes — mechanical fixes and AI-assisted reformatting — and like synthesis, nothing is saved until you choose to apply it.

Mechanical fixes (no AI)​

When you open the tab, REQQA runs a preview over the current content and reports what it finds. The mechanical fixes are deterministic — no model call, no token cost — and you choose which to apply:

  • Merge duplicate sections — when the same ## Heading appears more than once (a common side-effect of synthesis appending content), REQQA keeps the first, largest instance and folds any unique text from the duplicates into it, then removes the repeats.
  • Clean escaped characters — converts literal \n / \t sequences and collapses runs of blank lines so the markdown renders cleanly.
  • Remove stray placeholders — deletes leftover template prompts (the bracketed guidance text) from sections that already contain real content, while leaving placeholders in genuinely empty sections so you still see what is missing.

Applying mechanical fixes writes a requirements_history snapshot with the action Cleanup and bumps the revision, and reports a log of exactly what changed.

AI section reformatting​

For prose that is correct but poorly written — rambling, inconsistent, or hard to read — the tab also offers an AI-assisted reformat of an individual section. You pick a section, REQQA sends just that section's text to the model with a reformatting prompt, and you review the rewritten version before it replaces the original. Working a section at a time keeps the change small and reviewable rather than rewriting the whole requirement at once.

Size advisories and scope inflation​

The Clean Up preview also raises advisories that it never auto-fixes, because they signal a judgement call rather than a typo:

  • Oversized sections — a section past the word threshold is flagged with a suggestion to split it into sub-sections.
  • Oversized documents — the whole requirement is graded ok, yellow, or red by character count, warning that a very large requirement will tend to produce excessive analysis issues and is a candidate for splitting into children.

These advisories exist because a requirement that keeps growing under synthesis is often suffering scope inflation — it has quietly taken on responsibilities that belong in separate, focused requirements. The size warnings are the early signal; the cure is usually to decompose, not to keep editing one ever-larger document.

Planned cleanup tooling​

Two parts of the pipeline are designed but not yet built, and are mentioned here so the model is complete:

  • Section reordering — after many synthesis cycles, sections can drift out of the template's intended order because new content is appended at the end. A planned mechanical reorder would re-sequence a requirement's headings to match its template, with any unmatched sections moved to the end.
  • Issue deduplication (DEDUPER) — collapsing near-identical analysis issues before they reach synthesis, so the SYNTHESISER groups a cleaner input set.

Until those ship, reorder sections by hand on edit, and let synthesis grouping absorb overlapping issues.

How it fits together​

Synthesis and cleanup are the feedback half of REQQA's loop: analysis finds the problems, synthesis proposes the fixes and links them to the findings they resolve, and cleanup keeps the growing content well-formed. Run them as a cycle — analyse, synthesise the priority changes, clean up, and re-analyse — and a draft requirement converges towards one that is both correct and readable, with a full revision history of how it got there.