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 a collision so you don't accept two edits that fight over the same text. Review colliding proposals together and accept at most one, or fold them into a single manual edit.

Accepting, dismissing, 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.

If a direct-edit proposal's expected "before" text no longer matches the live requirement — because the content changed after the run started — REQQA does not blindly overwrite it. Instead the group is presented for manual review, showing the contributing issues and the current section text so you can make the edit by hand. This guards against applying a change to content that has moved on underneath it.

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.