Requirement Gaps and Use-Case Journeys

Overview

Every other requirements screen reports what Shift-Left Studio found. The Gaps & conflicts tab reports what it could not turn into a test, and why. Each untested requirement is listed under exactly one reason, written in plain words, so a long list becomes a handful of explanations — each with an obvious next step.

Some requirements are not single requests at all. A use case such as "the customer creates an order, adds an item, and pays" is a journey: several calls in a fixed order. When a use case records its calls in order, Studio builds a workflow test from it automatically as soon as every step has a test of its own. The Journeys panel, directly under the gaps list, shows which journeys are ready, which are blocked, and exactly which step is missing.

Key concepts

Before you begin

• Requirements must have been extracted from at least one document. See Working with Many Requirement Documents.
• Your API specification should be imported (Setup → API Specs) so requirements can be tied to endpoints.
• Tests are generated only from approved requirements.

Step 1 — Open the gaps list

1. Open your project's requirements and select the Gaps & conflicts tab.
2. At the top, if your project has several documents, the Across your documents panel lists disagreements between documents. See Duplicates and Conflicts Across Requirement Documents.
3. Below it, the list is grouped into sections. Click a section heading to expand it. Each section shows a count and the reason in its subtitle; each row shows the requirement's id, title, and the sentence it came from.

If nothing is missing, you see No gaps found — every extracted rule is scoped, consistent and testable.

Step 2 — Work through each reason

Each untested requirement is reported under the first reason that applies, in this order.

The tab also lists:

• Your document contradicts itself — one document states the same fact twice with different values. Fix the document, or edit one of the two rules so they agree.
• Rules that disagree with your API spec — a rule and the specification disagree, so one of them is out of date. The rule is not approved automatically until this is settled.
• Ambiguities the AI could not resolve, Information missing from your document, and Assumptions the AI had to make — the AI's own notes from extraction, shown as it wrote them. Use them as questions for the document authors.

Note: A disagreement between documents appears only once, in Across your documents, rather than also as a contradiction inside one document.

Step 3 — Link a requirement to its endpoints

For rules under Not tied to any endpoint:

1. Open the review list (Show requirements on a document's row, or Review all requirements on the batch bar).
2. Find the requirement. Its Applies to endpoints: line is highlighted as unresolved.
3. Expand the line and tick each endpoint the rule applies to.
4. The change is saved immediately. Approved rules that are linked produce tests the next time you generate for those endpoints.

Choose All endpoints (cross-cutting rule) only for rules that apply everywhere, such as an authentication rule.

Tip: The Project Assistant can suggest the most likely endpoints for a requirement, with the evidence for each, and offer to link them for you to accept.

Step 4 — Fill coverage gaps automatically (optional)

On the Coverage tab, click Fill coverage gaps above the per-endpoint coverage matrix. Studio synthesizes requirements for uncovered areas of the project and reports how many it created, or that no new gaps could be closed automatically. Gap filling cannot help a requirement that is not tied to any endpoint; link those first. See Coverage and Extraction Fidelity.

Step 5 — Build workflow tests from ready journeys

The Journeys panel sits directly under the gaps list: "A journey is several calls in order. It becomes a workflow test once every one of its steps has a test of its own."

1. Look at Ready to build (N). Each journey shows its title, id, and "N steps, every one of them already tested."
2. Click Build N workflow tests.
3. A confirmation reports "Built X and updated Y workflow test(s)." Any journey that could not be built is explained under Blocked.
4. Open the new workflows from your project's workflows to see the steps on the canvas.

You often do not need to click at all. Every time tests are generated, Studio checks the project's journeys a few seconds later and builds any journey whose steps are now all tested. Running it again updates existing journey workflows rather than duplicating them.

Step 6 — Unblock a blocked journey

Each entry under Blocked (N) gives the exact reason. The most common reasons:

If the project has no use cases with ordered steps, the panel shows No journeys in this project.

Below the Journeys panel, End-to-end flows this project could have suggests flows read from your specification and existing tests. Nothing there is created until you choose to build it.

Step 7 — Build a journey by name with the Project Assistant

You can ask the Project Assistant for a specific journey, for example "Build the workflow for REQ-4F21A9C0".

• If every step is tested, the assistant offers a card that builds that workflow. Accept it to build.
• If some steps have no test but their endpoints are in this project, the assistant offers one card that generates the missing tests and then builds the workflow. Accept it once; the workflow appears when generation finishes.
• If any step has no endpoint, the assistant explains which call the specification does not declare instead of offering to build.

The assistant never builds anything without your acceptance, and it will not generate tests into another project.

Understanding the results

Troubleshooting

Best practices

• Start with Not tied to any endpoint and Awaiting your decision; they usually account for most gaps.
• Write use cases with the method and path of each call, in order. That is what lets Studio build them as workflows.
• Treat no endpoint steps as questions for the API team: either the specification is incomplete or the requirement describes a call that does not exist.
• Share the AI's ambiguity and missing-information notes with document authors to improve the next version of the document.
• Revisit this tab after each extraction and each generation run.

Related articles

• Working with Many Requirement Documents
• Duplicates and Conflicts Across Requirement Documents
• Importing and Reviewing Requirements
• Coverage and Extraction Fidelity
• Requirements Traceability Matrix

For administrators (self-hosted installations)