# Re-scans and naming rules

<Availability permission="Features: Read to see a re-scan's changes. Features: Update to review, assign and apply them, and Features: Create to apply additions. Tags: Create to tag them, Comments: Create to discuss them. Knowledge base: Read to use documents as naming rules." />

Once your workspace has features of its own, running
[Feature discovery](/user-guide/product/features#discovering-features-in-your-code) doesn't change
your catalog. It builds on the features you have and proposes its changes for you to review. After
the first scan, that is a **re-scan**. Whenever you run Feature discovery, you can also give it
documents from your knowledge base as naming rules.

## Re-scanning your catalog

A re-scan reads your code the same way as the first scan, but **changes nothing** in your catalog.
It starts from the features you already have:

1. It groups the code it found under your own top-level domains and features, where they cover it,
   instead of inventing groups of its own.
2. It connects each existing feature to the code that is that feature: by its code, by its name and
   place in your hierarchy, and, for the rest, with short AI steps that work down your tree,
   parents first, and give a reason for each match. A feature with no code of its own yet is
   connected through its sub-features' code, or by its name and description.
3. It places what is new inside the existing feature or domain it belongs to. Where a domain has
   sub-features, a further AI step asks which of them each new part belongs inside, and gives its
   reason; a part that fits none of them stays directly under the domain.

It then lists the differences as a proposal for you to review:

- existing features it connected to code: the applications and code paths each would gain, and
  how it was matched (**Link**);
- code that isn't one of your features yet, placed inside the feature or domain it belongs to
  (**Add**);
- features it would name differently (**Rename**);
- features whose code sits with a different existing parent (**Move**);
- features whose code is now part of another feature (**Merge**);
- features whose code it no longer finds (**Remove**).

Finer-grained code inside a feature you already have is proposed as a new sub-feature of it. If it
isn't new, you can [link it to the feature it is](#to-link-an-addition-to-an-existing-feature)
instead of adding it. An addition appears at the top level only when nothing in your tree says
where it belongs. Your domains are never renamed, moved or removed, and no code is linked to a
domain: what the scan finds inside one is proposed under it. A move is only ever proposed between
two existing features. Every change shows why, the repositories it is about, and the code behind
it under **Evidence**.

The review also says how the matching went: how many of your existing features were matched and
how, and which were not, each with the reason. Features in **Backlog** or **Planned** are listed
apart, since no code is expected for them yet.

### When a first scan proposes

Feature discovery writes draft features directly only in a workspace that has no features of its
own. If you added or imported features before your first scan, or opened or edited one of the
suggestions your workspace started with, the first scan proposes its changes too, so it builds on
your tree instead of adding a second one beside it. The same goes for the catalog Productmind
builds after you import repositories: in a workspace that has features, it waits above the
**Features** list as a proposal.

A re-scan doesn't touch your features' specifications. It never proposes removing a feature just
because it didn't reach it, and proposes a removal only when every repository the feature's code
is in was fully read. A scan of some of your applications still recognizes a feature whose code so
far is in the others: when it finds that feature's code, it proposes linking the feature to it, and
the change says where the rest of its code is. It proposes nothing else about such a feature: no
rename, no move and no removal.

When the re-scan finishes, a band above the list (and in the Feature map) says how many potential
changes it detected, and that they need approval before anything changes. If it found none, nothing
appears.

Each re-scan is also listed in [Code](/user-guide/sessions/overview) with the other
scans. Its page reads **Re-scan**, and once the proposal is ready, **Review the proposal** opens it.
While it runs, its page shows its work as a conversation: each command it ran to install and read
your code with its output, and each AI step with what it was asked and what it answered.

## To start a re-scan

1. In the sidebar, choose **Features**.
2. Choose the sparkles button next to **+**.
3. Optionally, under **Documents shared with the agents**, change the documents that hold your
   naming rules. Your workspace's default documents are already there, and a change applies to
   this run only. See [Using your knowledge base as naming rules](#using-your-knowledge-base-as-naming-rules).
4. Choose **Re-scan**.

To re-scan only some of your applications, select them under **Applications** and start Feature
discovery from **Scan applications** there. See
[Applications](/user-guide/engineering/applications#to-run-feature-discovery-on-some-of-your-applications).
To re-scan one application, open it and choose **Scan application**, then **Feature discovery (this
application)**. Its **Features** view shows the band too, with **Review changes**. See
[Applications](/user-guide/engineering/applications#to-run-a-scan-on-one-application).

## To review a re-scan

1. On **Features**, choose **Review changes** in the band. The review opens as a page of its own,
   so you can bookmark its address or share it with a teammate. **Back to Features** returns to
   the list. Two rows stay at the top while you scroll: the filters (**All**, **Linked**,
   **Added**, and so on, then **Assignee** and **With comments**), the bulk actions and how many
   changes you've decided; then **Collapse all**, **Discard** and **Apply**.
2. Changes are grouped by kind, links first, and shown as a tree: a line runs down from each
   group to the changes in it. Additions are grouped once more, under **Added**, by the existing
   feature or domain they land in, in the order of your hierarchy, and each of those places has
   its own **Accept all** and **Decline all**, so you can decide on everything new in one area at
   once. Inside a place, an addition is followed by the additions proposed under it. Links,
   renames, moves, merges and removals are nested the same way: each sits under the change of the
   same kind on the feature above its own (see
   [Decisions passed down](#decisions-passed-down)). To fold a group or a place, choose its arrow
   or its line; to fold the changes under a change, choose the arrow beside it. **Collapse all** folds every group, which leaves a short list of
   the places that gain something, each with its count; **Expand all** opens them again. A
   place's **Accept all** and **Decline all** take all of its additions, folded or not. Each
   change shows what goes struck through and what comes in highlighted. For each change, choose
   **Accept**, **Amend** or **Decline**:
   - **Accept** takes the change as proposed.
   - **Amend** lets you change it first, right on the change: choose the proposed name and type a
     different one, then press Enter, or choose the proposed parent or the feature it merges into
     and search for a different one. Press Escape to keep the scan's proposal. The change then
     shows what the scan proposed. A removal and a link can't be amended.
   - **Decline** leaves your catalog as it is. A change you decline isn't proposed again on later
     re-scans; a different change to the same feature still can be.

   A decision passes down to the changes of the same kind under it, which show it with the
   **Inherited** mark. See [Decisions passed down](#decisions-passed-down).
3. Choose **Apply**. Once the changes are applied, you're back on **Features**.

### To link an addition to an existing feature

When an addition is really a feature you already have, under another name:

1. On the addition, choose where it goes (the feature or domain after **in**, or **the top
   level**).
2. At the top of the list, choose **It is an existing feature**.
3. Search for the feature and choose it. You can't choose a domain: a domain holds no code.

The change now reads **is**, then the feature, and nothing is added for it. To add it after all,
choose that feature, choose **Place it in a feature**, and choose where it goes. When you apply, its
code is added to that feature, and anything proposed under it is created under that feature. Later
re-scans read that code as the feature and don't propose it again, unless the code changes a lot.

Only the changes you accept or amend are applied, all at once. Nothing about an existing feature
changes unless a change you accepted says so: its applications and code paths are added only when
you accept its **Link**, and accepting one only adds to what the feature already has. Changes you
leave undecided stay as they are, and a later re-scan can propose them again. Your decisions are saved as you make them, so
you can review over several days, and several people can review together.

Some changes carry a note under them:

- **Edited by a person** marks a change to a name or a place someone chose by hand. **Accept all**
  skips these, and an accepted decision doesn't pass down to them, so you look at each one.
- **Changed since the scan** marks a feature someone edited after the re-scan read it. Applying it
  is refused until you decline it or amend it again.
- On a **Link**, the match reads **by code**, **by name**, **by AI**, **inherited** (through its
  sub-features' code) or **fold** (finer code that sits inside it). Matches **by AI** are
  highlighted, so you can check them first.
- **By AI** leads a reason that the scan's AI wrote, so you can tell it from one the scan worked out
  from your code.

Accepting a removal or a merge doesn't delete anything. The feature is marked
**Deprecated**, with a comment saying why. A merge also moves the feature's sub-features, tasks,
documents, dependencies and code paths to the feature it merges into. Code paths that someone
added by hand stay where they are.

If a change can't be applied, for example because its parent addition was declined, Productmind
applies nothing and marks each change that needs attention with the reason.

**Discard** drops the whole proposal without changing your catalog, and takes you back to
**Features**. Changes you declined stay remembered, and the tags held on the changes are dropped.
If you start another re-scan while a proposal is waiting, the new proposal replaces it when that
re-scan finishes. The decisions people made, the tags on the changes, the assignments people made
and each change's comments carry over to the same changes in the new proposal. Decisions a change
only inherited are worked out again there.

Changes about features you can't see aren't shown to you, and applying leaves them for someone who
can.

## Decisions passed down

A decision on a change passes down to the changes of the same kind under it, so you can decide a
whole branch of your hierarchy at once and change only what's different.

Each change follows the change above it:

- an addition follows the addition it's proposed under;
- a link, rename, move, merge or removal follows the change of the same kind on the nearest
  feature above its own in your hierarchy. A component's link follows its feature's link, even
  when the feature between them has no link.

A change with nothing above it stands on its own.

A change you haven't decided takes the decision of the change above it, down the whole branch:

- **Accept** and **Amend** pass down as **Accept**.
- **Decline** passes down as **Decline**.
- If the change above is undecided, so is the change under it.

A change marked **Edited by a person** or **Changed since the scan** doesn't take an **Accept**
from above. It stays undecided for you to look at, and so do the changes under it until you decide
it. It does take a **Decline**.

An inherited decision shows on the change in a quieter style, with the **Inherited** mark. Point at
the mark to see where it comes from, such as **Follows the decision on FEAT-12 Billing**, and the
line under the change says **Inherited from FEAT-12 Billing**. If the decision comes from a change
about a feature you can't see, the change says **Inherited** only. The count of decided changes
says how many are inherited.

Inherited decisions are saved like your own. Everyone reviewing sees them, **Apply** applies them,
and a change declined this way isn't proposed again on later re-scans. Changes left undecided are
still left as they are.

### To override an inherited decision

1. On the change, choose a different decision.

The decision is now yours, and the changes under it follow it instead. To keep the inherited
decision as your own, choose the decision the change shows. To have the change follow the change
above it again, choose your own decision once more: that clears it.

## Deciding, tagging and assigning several changes

**Accept all**, **Decline the rest**, and a place's **Accept all** and **Decline all** decide only
the top changes among the ones they take. The changes under those follow them, with the
**Inherited** mark. The totals are the same as if every change were decided one by one.

### To decide, tag or assign several changes at once

1. Select the checkbox next to each change you want, or the checkbox on a place or a kind of change
   to select all its changes, folded or not. A checkbox on a place or a kind shows when some of
   its changes are selected.
2. In the bar at the top, which now says how many changes you selected, choose **Accept**,
   **Decline**, **Tag...** or **Assign...**.
3. For **Tag...**, choose a tag to add or remove. For **Assign...**, choose the people or teams.

The selected changes take the decision, the tag or the assignees. **Accept**, **Decline** and
**Assign...** decide or assign the top changes you selected, and the selected changes under them
follow them. A change marked **Edited by a person** or **Changed since the scan** that you select
takes **Accept** itself, because you chose it.

To clear the selection, choose **Clear**. Changing a filter clears it too. Without
**Features: Update**, the review shows no checkboxes.

## Tagging changes

You can tag additions, links, renames and moves in the review, the same way you tag features, so
your new and changed features are organized by the time you apply.

### To tag a change

1. Point at the change and choose its tags chip, or the tag icon on a change without tags.
2. Type a tag and press Enter, or pick one of your workspace's feature tags.

The tag appears on the change and, with the **Inherited** mark, on every change under it. A new tag
is spelled the standard way: see [How tags are spelled](/user-guide/tags#how-tags-are-spelled).

### To remove a tag from a change

1. Choose the change's tags chip.
2. Choose the **x** on the tag.

The tag leaves the change and the changes under it. If the tag was inherited, adding it back on
the change restores it there and under it.

To tag or untag several changes at once, select them and choose **Tag...**: a tag you add goes on
every selected change, and a tag you remove leaves every selected change that carries it. Merges and
removals take no tags, so **Tag...** says how many of the selected changes it tags, such as
**Tag 40 of 42**.

### When tags land on your features

Tags are kept on the proposal until you apply it. **Apply** adds them to the feature of each change
that is accepted or amended, inherited decisions included:

- an addition's tags go to the new feature, or to the existing feature you linked it to;
- a link's, rename's or move's tags go to that feature.

A feature with several applied changes gets all their tags. A tag the feature already has, in any
spelling, stays as it is. A tag someone once removed from the feature, or rejected as a suggestion,
is added back. Tags on declined or undecided changes are dropped. The message after **Apply** says
how many features were tagged.

## Who a change is assigned to

When a re-scan finishes, each change is assigned to the owners of its feature: the feature's
assignees, people or teams. A feature without assignees takes them from the nearest feature above
it that has some. An addition takes them from the existing feature it lands in. A change with no
owner anywhere above it is unassigned. These changes show their assignees with the
**Feature owner** mark.

The owners are worked out once, when the re-scan finishes. If a feature's assignees change during
the review, its changes keep the earlier owners until someone reassigns them, or until the next
re-scan.

Assigning a change is guidance only. Anyone who can review a re-scan can decide, tag and comment on
any change, whoever it's assigned to, and nobody is notified of an assignment.

### To reassign a change

1. Choose the change's assignees, or point at the change and choose the assign icon.
2. Choose people or teams.

The change is assigned to them, and so are the changes under it, except a change someone assigned
on its own. Those changes show **Inherited from**, then the change they follow. To assign every
change of a place or a kind, choose **Assign...** on its heading; to assign the changes you
selected, choose **Assign...** in the selection bar.

To leave a change unassigned even though its feature has an owner, remove everyone from it. To
give a change its feature's owners again, choose **Back to automatic**.

### To see the changes assigned to you

1. In the toolbar, choose **Assignee**.
2. Choose **Assigned to me**.

The review shows the changes assigned to you, or to a team you belong to, and the count says how
many of yours are undecided. You can also choose **Unassigned**, or a person or team, and
**Anyone** shows every change again. The filter is part of the page's address, so you can share a
link to someone's changes.

## Discussing a change

Every change has its own comment thread, so a question about one change stays with it.

### To comment on a change

1. Point at the change and choose the comment icon, or its comment count once it has comments.
2. In the panel that opens at the right of the review, write your comment. Type @ to mention
   someone.

The comment appears in the change's thread, and the change shows its comment count. Everyone you
mention is notified, and the notification opens the review on that change, with its thread open.
You can mention only people who can read features.

To see only the changes people are discussing, choose **With comments** in the toolbar.

Only people who can see a change, which means every feature it names, can read or write its
comments. When a newer re-scan replaces the proposal, each thread moves to the same change in the
new one. A thread whose change isn't proposed again stays with the replaced proposal, which is no
longer shown. After the proposal is applied or discarded, its threads stay on the review page: you
can't decide anymore, but you can still reply.

## Using your knowledge base as naming rules

When you start Feature discovery or a re-scan, you can add up to 10 documents from your
[knowledge base](/user-guide/knowledge-base): your naming conventions, a glossary, or how your
product divides into domains. Their text reaches the step that groups your code into domains and
features, and your rules win over Productmind's default naming where the two disagree.

Your workspace's default documents are added for you. An Owner or Admin sets them in
[Feature discovery settings](/user-guide/settings/workspace-settings/feature-discovery#to-set-the-default-documents).
Add or remove documents in the start dialog to change them for that run only: the default stays as
it is. Until a default is saved, the documents the last run used are added instead.

A scan that starts without anyone choosing documents uses the default as it is: the scan that
follows detecting your applications, and a scan started through the
[API](/user-guide/tools/api-access) or an [AI assistant](/user-guide/tools/ai-assistants) that
doesn't name any documents. To start one there with no documents, send an empty list. A default
document deleted since it was saved is skipped, and the scan runs with the others. If you can't
read the knowledge base, your scans use no documents.

Very long documents are shortened to fit, and the Feature map shows which documents the last run
used and whether any was shortened.

:::note
On your own [Productmind agent](/user-guide/tools/productmind-cli), using documents, and any scan
that proposes its changes, need a recent version. If yours is too old, the scan stops and asks you
to run `pm update`, then scan again.
:::

## Permissions

| To | You need |
| --- | --- |
| See a re-scan's changes | **Features: Read** |
| Start a re-scan | **Features: Create** |
| Use knowledge-base documents as naming rules | **Knowledge base: Read**, as well |
| Set the workspace's default documents | The **Owner** or **Admin** role, and **Knowledge base: Read** |
| Review a re-scan (accept, amend, decline, apply, discard) | **Features: Update** |
| Apply changes that add features | **Features: Create**, as well |
| Assign changes | **Features: Update** |
| Tag changes, and remove their tags | **Features: Update** and **Tags: Create** |
| Read a change's comments | **Comments: Read**, and you must be able to see the change |
| Comment on a change | **Comments: Create**, and you must be able to see the change |

Without **Features: Update**, you can open the review, but you can't decide on it, select changes
or assign them.

## Limits

- The review counts every change you declined before that a re-scan found again, and lists the
  first 200 by name.
- It counts every existing feature that wasn't matched, and lists the first 500. Features you
  can't see are counted, not named.
- Applying additions counts toward your plan's feature limit. An apply that would go over it is
  refused, and nothing is applied. See
  [Plans and limits](/user-guide/reference/plans-and-limits#reaching-a-limit).
- A change holds up to 20 tags of its own, and can be assigned to up to 20 people and teams.

## Related topics

- [Features](/user-guide/product/features)
- [Applications](/user-guide/engineering/applications)
- [Knowledge base](/user-guide/knowledge-base)
- [Tags](/user-guide/tags)
- [Feature discovery](/user-guide/settings/workspace-settings/feature-discovery)
