Re-scans and naming rules
Once your workspace has features of its own, running Feature discovery 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:
- 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.
- 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.
- 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 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 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
- In the sidebar, choose Features.
- Choose the sparkles button next to +.
- 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.
- 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. 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.
To review a re-scan
-
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.
-
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). 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.
-
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:
- On the addition, choose where it goes (the feature or domain after in, or the top level).
- At the top of the list, choose It is an existing feature.
- 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
- 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
- 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.
- In the bar at the top, which now says how many changes you selected, choose Accept, Decline, Tag... or Assign....
- 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
- Point at the change and choose its tags chip, or the tag icon on a change without tags.
- 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.
To remove a tag from a change
- Choose the change's tags chip.
- 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
- Choose the change's assignees, or point at the change and choose the assign icon.
- 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
- In the toolbar, choose Assignee.
- 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
- Point at the change and choose the comment icon, or its comment count once it has comments.
- 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: 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. 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 or an AI assistant 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.
On your own Productmind agent, 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.
- A change holds up to 20 tags of its own, and can be assigned to up to 20 people and teams.