Skip to content

Analyst flow

This is the recommended end-to-end path for an analyst working from business intent toward validated coverage. Follow it when you want a practical sequence instead of learning each analyst page in isolation. It matters because later steps such as semantic search, Use Case generation, and gap analysis are much more useful when the earlier Requirement work is already clean. Before you start, make sure you know which project and specification own the work. A small Epic can usually be worked through in 15 to 30 minutes, while a larger or imported scope will take longer.

Flow overview

  1. Open the target project and specification workspace.
  2. Create or generate the first Epic.
  3. Review, enhance, and finalize Requirements.
  4. Connect Requirements to Use Cases.
  5. Generate Use Cases as new items.
  6. Review, enhance, and finalize Use Cases.
  7. Add Test Cases when enabled.
  8. Run gap analysis.
  9. Add only justified new Requirements.
  10. Review handoff readiness.

Page guides used in this flow

1. Start in the right project context

Open Projects, choose the correct project, then move into the specification that should contain the work. Confirm that the project language and access mode match the intended collaboration model.

From the project page, use Workspace on the specification row. The Specification workspace is the best first stop because it shows the preparation path: Start, Draft, Review, Connect, Validate, and Handoff. It highlights the next useful action, review items, coverage gaps, and readiness blockers before you enter detailed tools.

The workspace keeps the same product terminology as the detailed pages: Epics, Requirements, Use Cases, Test Cases, and Ubiquitous Language.

2. Create or generate the first Epic

In the Specification workspace, follow the recommended next action. If no scope Epic exists yet, open Detailed tools and create the first Epic with AI New.

Provide:

  • Epic key
  • Epic name
  • the business Requirement text

What to expect:

  • the modal closes after the generation job is accepted
  • a new Epic is created
  • starter Requirements are created under that Epic
  • you can follow the queued work in the Background jobs popup by clicking the AIKOZO logo in the top bar

Use manual creation only when you already have the structure prepared by hand.

3. Enhance and finalize Requirements

In the Specification workspace, open Work on the specification document and choose Requirements for the Epic. You can also open the same SmartDoc document from the detailed Epic page.

Recommended approach:

  1. Review the generated or imported Requirement list. Note: A small SEM6 superscript beside a Requirement, Use Case, or Test Case title means that artifact already has its semantic embedding stored in the vector database. A blue LINKS superscript means the artifact has at least one confirmed graph relationship; gray means no confirmed relationship is currently present. If SEM6 is missing, the normal fix is to enhance the artifact and save the finalized text.
  2. Use Enhance new for untouched items when a first quality pass is needed.
  3. Open each important Requirement and review:
  4. original text
  5. saved final text; the final text editor is empty until final text is saved
  6. enhancement history
  7. whether it should stay bookmarked for follow-up later
  8. Edit the final text directly when needed. Use Use as final beside the final text when the original wording should overwrite final text without running AI. This saves the change and returns the item to draft.
  9. Use Defer when the Requirement stays valid but should be handled later, by a third party, or simply kept around as not relevant right now.
  10. Use Finalize only after the wording is precise, testable, and implementation-neutral.

In the document view, Requirement and Use Case blocks are edited in a continuous structured ProseMirror workspace. Canonical English and localized text remain separate fields. In bilingual projects, canonical English is hidden by default and can be revealed with Show Canonical EN. In Use Cases mode, the document shows only title and canonical text. Add block or Ctrl+Enter creates a new record after the current cursor position. Record-backed Requirement and Use Case blocks can also be deleted from their block controls. Split here patches the current Requirement text and creates a new draft Requirement record. Merge previous combines text into the previous Requirement and marks the merged-away source Requirement deferred. AI enhancement is preview-first: review the proposed change, then explicitly apply or discard it.

Requirement review checklist

  • Is the statement clear and singular?
  • Does it avoid unnecessary implementation detail?
  • Can another person verify it?
  • Is the status correct for the current maturity?

4. Create links between Requirements

Open a Requirement and go to Links.

There are two modes:

  • Suggest links uses AI to propose candidate relationships.
  • New creates a link manually.

Use links only when they are meaningful. Good examples:

  • one Requirement depends on another
  • two Requirements relate to the same behavior cluster
  • two Requirements conflict and need explicit visibility

Approve or reject suggestions deliberately. Link quality matters more than link count.

5. Generate Use Cases automatically as new items

Return to the Specification workspace, open Work on the specification document, and choose Use Cases for the Epic. You can also use the detailed Epic page when you need the full advanced controls.

You can:

  • create a Use Case manually with New
  • create a Use Case with AI from selected Requirements with AI New
  • auto-generate Use Cases as new items by semantically grouping Requirements with AI Auto New

For analyst flow, the normal path is to generate Use Cases from the refined Requirements rather than from raw drafts.

AI New only offers final Requirements for selection, and generation still validates that selected Requirements are final-ready before queuing. Requirements marked deferred are skipped here. They remain searchable, but they do not participate in Use Case generation, Ubiquitous Language analysis, or gap analysis.

When you start AI work and the result is not immediate, open the Background jobs popup by clicking the AIKOZO logo in the top bar. Use it to confirm whether the job is queued, running, completed, or failed.

6. Enhance and finalize Use Cases

Open each generated Use Case and review:

  • whether the SEM6 superscript is present in the Epic list when semantic indexing should already exist
  • whether the LINKS superscript is blue when confirmed Use Case graph relationships already exist
  • original text
  • final text
  • covered Requirements
  • enhancement output
  • whether the item should stay bookmarked for later follow-up

Finalize a Use Case only when the flow is understandable, complete enough for coverage work, and aligned with the finalized Requirements.

Use Defer when the Use Case stays valid but the actual delivery belongs outside the current team or stream, should happen later, or is being retained for context only.

If SEM6 is still missing after review, enhance the Use Case and save the finalized text so semantic indexing has the content it needs.

On Requirement, Use Case, and Test Case detail pages, Use as final appears in two contexts. The button beside original/final text copies original text into final text and saves the item as draft. The button in enhancement history copies that enhancement result into final text.

7. Create links between Use Cases

Open a Use Case and use the Links tab.

Use links when one Use Case depends on another or when the relationship helps readers understand sequence and scope. Do not add links only because the system can suggest them.

8. Perform gap analysis

From the Specification workspace, use AI-assisted actions -> Run gap analysis or open Detailed tools -> Gap analysis.

Note

Gap analysis is only useful once there is enough semantic content in place, so work through the earlier analyst-flow steps actively and thoroughly first. Deferred Requirements are intentionally excluded from this analysis.

Typical sequence:

  1. Select the Epic scope or keep all Epics in the specification.
  2. Keep the default thresholds first unless you have a reason to tune them.
  3. Run the analysis.
  4. Inspect the Use Case rows and their coverage maps.

The results table opens on the latest analysis report. Use the previous and next controls in the table header to review older or newer retained reports.

If the run takes longer, check the Background jobs popup for the current state and any reported failure details.

Interpretation:

  • Covered means the current Requirements likely support the Use Case steps.
  • Weak means the coverage exists but is not convincing enough.
  • Gap means the Use Case contains behavior that is not well supported by the current Requirements.

Coverage maps open for the selected completed report. Review decisions remain visible when a step has been accepted as-is or converted into a Requirement.

In the Coverage map, the Step badge shows the extracted actor and sequence:

  • U means a user, customer, or other external actor step.
  • S means a system, service, or platform step.
  • X means the actor was unclear in the source Use Case.

The number is the step order in the extracted Use Case flow, so U1 is the first extracted user step and S2 is the second extracted system step.

Use the Score as a semantic match ratio from 0.00 to 1.00. The current thresholds decide the initial status:

  • scores below Gap < are shown as Gap
  • scores from Gap < up to, but not including, Covered >= are shown as Weak
  • scores at or above Covered >= are shown as Covered

For weak findings, use the ratio to the covered threshold as a review cue: score / covered threshold. With the default Covered >= 0.55, a weak score of 0.50 is about 91% of the covered threshold, while 0.36 is about 65%. This ratio helps triage, but it is not a substitute for reading the matched Requirement.

Accept a weak finding only when the best matching Requirement already satisfies the intent of the Use Case step and the remaining ambiguity is an acceptable delivery risk. After you select Accept, the step is marked Accepted and the main report no longer counts it as an unresolved weak or gap finding.

If a later analysis run extracts the same actor step with the same best Requirement evidence or similar wording, the accepted decision is carried forward into that run.

If the match only overlaps in wording, misses a rule, changes the actor, or leaves behavior ambiguous, do not accept it just to clear the report. Create a Requirement from the gap, or update the existing Requirement through the normal Requirement workflow.

9. Add only justified and meaningful Requirements

Gap analysis is a decision aid, not an order to create more Requirements.

Create a new Requirement from a gap only when:

  • the missing behavior is truly in scope
  • the Use Case step is meaningful enough to deserve its own Requirement
  • the Requirement would improve clarity or delivery confidence

Do not create Requirements for trivial wording differences or obvious duplications.

10. Final analyst checks

Before you hand work downstream:

  • important Requirements are finalized
  • Use Cases cover the intended business behavior
  • Test Cases cover the important Use Cases when Test Case support is enabled
  • links describe real relationships
  • gaps were reviewed, not blindly converted into more items
  • the Epic status reflects the true maturity of the analysis

Optional but useful:

  • review and accept Ubiquitous Language terms in detailed tools
  • export finalized Requirements, finalized Use Cases, and available Test Cases when a formal handoff is needed