Using Smart Merge

User Guide

BriefSpec

Introduction

The Smart Merge feature helps you identify duplicate or overlapping requirements in a project Backlog and streamline cleanup. It analyzes selected User Story or RTM requirements (based on the project’s requirement form), highlights potential duplicates, and can export an analysis report for review.

In addition to insights, Smart Merge lets you choose which requirements to merge and which to archive. Surviving records are updated with consolidated content; other records in a merge are set to Archived (not deleted) so history and traceability remain.

Purpose

Smart Merge uses AI to identify overlapping or duplicate requirements in the Backlog and suggest potential merges. It helps reduce redundancy and improve backlog quality. Analysis and merge fields depend on whether the project uses User Stories or RTM requirements.

Ways to start Smart Merge

Select one to twenty Backlog requirements first, then launch Smart Merge (preselection can skip the software/status prompts when selected rows already have Pillar and Epic).

Open Smart Merge directly from the Backlog toolbar without selecting rows first.

Both options follow the same review and execution workflow after launch. Selections must match the project requirement form (User Story or RTM only — mixed types are not allowed).

Smart Merge workflow overview

Define scope (Software and Epics)

Select Status filters

Confirm selections

Narrow requirements (if needed)

Run AI analysis

Review merge suggestions

Execute merge or restart

Selecting requirements for Smart Merge

Accessing Smart Merge

From the Backlog toolbar:

Select requirements (optional)

Click Smart Merge

The Smart Merge dialog opens.

Navigate to the Backlog feature within the project and click the Smart Merge icon shown below.

Access is controlled by privilege, plan, and AI availability — not by a hard-coded Application Admin or Project Manager role. Smart Merge appears when your role has Backlog privilege Smart Merge (feature key smart-merge). By default this privilege is Hidden for all roles (including Project Manager) until an administrator grants Read & Edit. The button also requires plan entitlement smart_merge, tenant AI features enabled, a non-draft project, and at least one Backlog requirement. Plan-locked tenants see an upgrade message; AI-disabled tenants cannot use Smart Merge. Click the button to open the selection screen as below.

Requirement types (User Story vs RTM)

Smart Merge supports the project’s Backlog requirement form only:

User Story projects — analysis uses Description and Acceptance Criteria; execution writes NEW DESCRIPTION and NEW ACCEPTANCE CRITERIA on the survivor.

RTM projects — analysis uses Title and Description; execution writes NEW TITLE and NEW DESCRIPTION on the survivor.

Preselected rows must be homogeneous and match the project form. Mixed User Story + RTM selections are blocked.

Access prerequisites

Role privilege: Backlog > Smart Merge (smart-merge) set to Read & Edit for roles that should run merges. Default for system roles is Hidden.

Plan entitlement: smart_merge must be active on the tenant subscription.

Tenant AI features must be enabled; otherwise Smart Merge stays unavailable.

Project must not be in draft; Backlog must contain requirements; at most 20 rows may be preselected from the toolbar.

Step 1 – Select Software and Epics

When Smart Merge opens without a valid preselection, you may see: “Please select Software and the Epics.” Each scope row requires Pillar (Software) and Epics/Modules.

Select Software first:

Click Select Pillar.

Choose the appropriate pillar.

The Epic field remains disabled until Pillar is selected.

Select Epics:

Click the Epics/Modules field.

Select one or more epics or modules.

Add or remove scope rows:

Click the + icon to add another software/epic combination.

Click the trash icon to remove a scope row.

Typically, the same software only needs to be selected once.

Once all required rows are completed, click Continue.

Step 2 – Select Status filters

You will see: “Please select one or more Status values.” Choose the statuses to include (Draft, Pending Review, Rejected, and Verified are available). Prefer Draft if you intend to execute merges afterward.

After selecting statuses, close the dropdown to confirm selections. The selected statuses are added to the AI conversation context.

Step 3 – Review summary and confirm

The assistant displays a summary containing selected software/epic combinations and selected statuses. This acts as a confirmation checkpoint before analysis begins.

If changes are needed, use Reset or Start Again later in the flow, then rerun the process.

Click Get matching Requirements once the details are finalized. Use Reset to clear inputs. While the request runs, the button may show Analyzing…; use Stop Analysis to cancel.

Get matching Requirements fetches Backlog items that match your software/epic and status filters, then continues into AI duplicate analysis when the result set is within the allowed limit.

If more than 20 requirements match, you must manually select up to 20 from the filtered list before analysis continues.

Step 4 – Select requirements for analysis (if prompted)

If many requirements match your filters, the system may display “Select requirements for analysis (n/20 selected)”.

Select the requirements to analyze.

Maximum allowed: 20 requirements.

Click Analyze Selected.

If this screen does not appear, the filtered result set is already within the allowed limit.

Step 5 – Run analysis

When the picker is shown, click Analyze Selected to send those requirements to the AI engine. If the picker is skipped, analysis continues from Get matching Requirements. Progress messages appear in the dialog while the request runs — keep the window open.

During analysis you can:

Use Stop Analysis to cancel an active request.

Use Reset to clear the current analysis state and start over.

Reset is disabled while analysis is running or while the requirement selection panel is open.

After analysis, the application creates comparison groups of matching requirements. Review each group as shown below. If no duplicates are found, analysis completes with an informational message.

Step 6 – Review merge suggestions (additional guidance)

Results are displayed in comparison groups. Each group includes a source requirement ID, suggested target requirement IDs, match percentage, and differences. IDs use the project form prefix (for example US… or RTM…).

Viewing requirement details:

Hover over underlined IDs to view requirement title, software, and epic/module.

Use the in-card navigation controls to move through suggestion groups.

Status displaying the number of duplicate groups found.

For each group, choose Merge Requirements or Ignore at the group level (or use pair-level controls when shown). By default, the flag is set to Ignore.

If you choose Merge, you can pick the surviving ID for each pair of requirements as shown below, or

make the decision at the group level for the requirement ID to merge into, as below.

The To be merged ID dropdown lists requirements in the group — choose the survivor that will keep the consolidated content.

If the Merge/Ignore decision is made at group level, pair-level decisions are not available, and vice versa.

Use the Download icon to export all groups to Excel for offline review, audit tracking, or team collaboration.

Once a decision has been made for a group, click Next to navigate to the next group.

You can cancel Smart Merge and return to Backlog, or click Reset to start over at any time before execution completes.

Draft-only merge rules

Smart Merge execution is only allowed when ALL requirements involved in the merge are in Draft status — including the source and every target. The UI tooltip states that merge is only possible when requirements are in Draft status.

Important limitation:

Analysis results may still appear for informational purposes.

If non-draft items are included, merge action controls remain hidden.

You cannot merge Draft and Verified (or other non-Draft) requirements together.

If needed, adjust statuses or filters and rerun analysis.

When the user reaches the last group, there is an option to view the selections made. See screen below.

Clicking Show Selections opens the Merge/Ignore decisions for each group. Only groups marked Merge are listed, with the group number and To be merged ID.

From there, proceed with the merge as selected, or go back and start again.

Once you proceed with the merge, the application starts the Smart Merge Execution dialog.

Step 7 – Proceed or start over

Use Proceed with Merge to apply supported merges. Use Start Again for a fresh Smart Merge session with different scope, statuses, or requirements.

Before executing, review selections carefully. Smart Merge updates the surviving requirement, archives the other IDs in each merge group, and writes consolidated content via AI.

The screens below show the application after you click Proceed with Merge.

Smart Merge execution dialog

During execution, a separate Smart Merge Execution dialog handles the merge operation for each selected group.

Do not close the dialog during active processing. Closing early may interrupt the merge operation.

The application works on one group at a time and shows merge progress. When a group succeeds, it updates the surviving requirement and lists Archived IDs. Columns depend on the project requirement form: for RTM, NEW TITLE and NEW DESCRIPTION; for User Story, NEW DESCRIPTION and NEW ACCEPTANCE CRITERIA.

As each group runs, Status moves from Pending to In Progress to Success or Failed.

Any error details appear under the Error column.

The screen below shows a successful completion state.

On success you also see a toast: “Smart merge completed”.

After merge, download results with Download execution results to Excel.

Click Close to return to the start of the Smart Merge screen (or dismiss the dialog).

Example: if requirements A and B are merged into B, A is archived and B keeps the consolidated content.

Archived is a Backlog status for items that are no longer active but are kept for history and traceability — they are not deleted. Requirement activity may show Merged Requirement / Archived Requirement for Smart Merge actions.

Archived items can return to the workflow only via allowed status changes (typically Draft or Pending Review) and follow the same transition rules as other Backlog statuses.

Best practices

Confirm access first — Smart Merge privilege (smart-merge), plan feature smart_merge, and tenant AI.

Use Draft status for merge candidates — all intended merge records must be Draft before execution.

Limit scope when possible; smaller analysis sets typically produce more focused suggestions.

Review suggestions carefully; AI recommendations should always be validated before execution. Export Excel results for audit tracking.

Re-run analysis when needed by adjusting scope, statuses, or requirement selection. Keep User Story and RTM projects separate — do not mix types in one run.

Cancelling Smart Merge

Use the dialog Close / Cancel control (before or after execution, when enabled) to exit Smart Merge. Closing during analysis or execution may interrupt processing and discard unsaved merge selections. Cancel only when you intend to exit without completing the process.

Outcome

After successful execution, duplicate or overlapping requirements are consolidated, backlog quality improves, and survivors carry the merged content while non-survivors remain Archived for history.