Recommendations are the rules that turn a score into an action. Here is how to write the conditions, choose the action and its button, use variables so one number controls many rules, and prove it works before anyone sees it.
TABLE OF CONTENTS
What a recommendation is
One sentence: when these conditions are true, offer this button.
Scoring tells you what IRIS thinks about an asset. A recommendation is what you do about it. Each one is a rule with four parts:
- Title & Description - how users will read it.
- Conditions - which assets it applies to.
- An action - what happens when someone acts on it.
- A button title - the words the user actually clicks.
Recommendations are yours to write. IRIS ships with a preset list, but you can modify everything.
Where to find it
Like scoring, recommendations are configured per use case. Rules written for Ideation never apply to Project Management.
Settings → Use cases → [your use case] → Recommendations
Set scoring up first
Most useful conditions reference score dimensions. The condition builder offers your dimension names, so configuring scoring first means you can write the rules you actually want rather than the ones your current configuration allows.
The recommendations list
| Column | What it shows |
|---|---|
| Grip handle | Drag a row to change its priority. |
| On | Enables or disables the rule without deleting it. A disabled rule matches nothing and is offered to nobody - the safe way to retire a rule you may want back. |
| Rule | Title and description. Click anywhere on the row to open it for editing. |
| Action | Which action fires when a user acts on it. |
| Conditions | A plain-language summary of the condition tree, so you can scan the list without opening each rule. Hover for the full text when it is truncated. |
| Priority | The row's position in the list, numbered from 1. It is not a field you type. |
| Row menu | Move to top, Move up, Move down, Move to bottom. Use these instead of dragging when you prefer the keyboard. |
| Pencil · Trash | Edit, or delete permanently. Deletion asks for confirmation and cannot be undone - prefer the On toggle unless you are certain. |
Priority and ordering
Position is the priority. There is no priority number to type; the rule at the top of the table is priority 1, and moving a row renumbers everything automatically.
Priority decides which rules come first when several apply, so put the rules that represent your most urgent work at the top. A rule far down the list is not weaker - its conditions are evaluated exactly the same way - it is simply presented later.
Because priority is a property of the whole workspace rather than of one person, it is worth agreeing the order with whoever runs the funnel rather than tuning it privately.
Title and description
| Field | What to put in it |
|---|---|
| Title* | What the rule is called in the list. Write it as the situation, not the action - “{asset_type} missing a clear problem statement” reads better in a list than “Send to clarification”, which is what the button already says. |
| Description* | Explains to the user why they are seeing this. It is user-facing text, so write it for them, not for you. You can insert a variable's current value by writing its name in braces {clarity_threshold}- so the description stays accurate when you change the number later. |
| Enabled / Disabled | The toggle in the page header. New rules start enabled - set it to disabled while you are still drafting. |
{asset_type} is a special system variable you can use in titles and descriptions for dynamic presentation of asset type (e.g., idea, project etc).
Conditions
Conditions decide which assets the rule applies to. Every rule needs at least one.
The anatomy of a condition
Each row reads left to right as a single sentence:
| Field | Dimension | Operator | Value |
|---|---|---|---|
| Score (dimension) | Clarity | ≤ | 55 |
| What you are testing | Only for score fields | How to compare | Literal, or bound to a variable |
Which operators you get depends on the field's type. Number fields offer =, ≠, ≤, ≥, <, >. Text and list fields offer is, is not, contains, does not contain. Yes/no fields offer only is. Choosing a different field resets the operator and value, because the old ones may not make sense any more.
AND, OR, and groups
Conditions live inside groups, and a group is either an AND group or an OR group.
- AND - every condition in the group must be true. Use it to narrow.
- OR - any one is enough. Use it to widen.
Groups can be nested, which is how you express anything real. “Low clarity or low feasibility, but only while still in evaluation” is an AND group containing one plain condition and one nested OR group - build that by adding a condition for the state check, then adding a group, switching it to OR, and putting the two score checks inside it.
Mind the shape, not just the parts
The most common mistake is putting everything in one flat AND group. That rule fires only for assets that fail on every count, which is usually far fewer than you intended - often zero. If a rule matches nothing, check the shape before you loosen the numbers.
Literal values and variables
A value can be typed directly, or bound to a variable with Bind to variable…. A bound value shows as a coloured chip; the small × on the chip unbinds it and returns to a typed value. Binding is strongly recommended for any threshold you might tune.
The condition catalog
Everything you can test, and what it means.
| Field | Type | What it tests |
|---|---|---|
| Score (dimension) | number | One named scoring dimension, 0–100. Pick the dimension in the second dropdown. The list is your own dimensions for this use case. |
| Overall score | number | The weighted total across all active dimensions. |
| In External state group | yes / no | Whether the asset sits in a state group marked External - this state group is usually where assets that are closed, duplicated or waiting clarifications are held. |
| In first state group | yes / no | Whether it is still at the very beginning of the workflow - typically freshly submitted or initially reviewed. |
| In last state group | yes / no | Whether it has reached the end of the workflow. Add “is false” to stop a rule chasing assets that are already finished. This is the last state group before External on your workflow. |
| Voting score | number | The community voting result. |
| Campaign alignment | list | How well the asset answers its campaign brief: Strong, Partial, Weak, Off Brief, or None. |
| Review committee - average score | number | The mean score from committee reviewers. |
| Review committee - reviewers count | number | How many reviewers have scored it. Useful for finding assets with too little review to decide on. |
| Review committee - score advantage by IRIS | number | How much higher IRIS automated review committee scored the asset than the reviewers did. Finds things people may be overlooking. |
| Review committee - score advantage by reviewers | number | How much higher the reviewers scored it than IRIS automated review committee did. Finds things people see value in that the model does not. |
Actions and button names
The action is what happens. The button title is what it says.
These are two separate fields on purpose. The action is a fixed behaviour; the button title is your wording, and it is what your users read.
| Action | Default button title | Use it to |
|---|---|---|
| Send to clarification | Send to clarification | Return the asset to its author for more detail. |
| Process | Evaluate | Move the asset onward for assessment. |
| Close / Reject | Prepare closure | Begin closing an asset that will not proceed. |
| Notify author | Notify author | Tell the author something without changing the asset's state. |
| View Review Committee summary | Review evaluation | Open the committee's consolidated scoring. |
| Open campaign overview | View campaign | Step up from the asset to its campaign. |
| Redirect | View page | Send the user to any URL you specify. It must be a full address starting with https:// |
How the button title behaves
Choosing an action fills the Action button title with that action's default. Keep changing actions and the title keeps updating - until you edit the title yourself. From that moment it is yours, and switching actions will never overwrite it again. So you can safely explore actions first and word the button last.
Write the button as the thing that will happen, in your organisation's language. “Ask for more detail” may serve your users better than “Send to clarification” - the underlying action is identical.
Actions and permissions
Buttons are evaluated in real-time against the user's permissions and will only be visible if the user is allowed to execute this action.
Variables and why they matter
A variable is a number you name once and reuse everywhere. They are the difference between a rule set you can tune and one you have to re-edit.
Suppose four rules all treat “low clarity” as 55 or below. Typed as literals, that number lives in four places. Raising the bar to 60 means opening four rules, changing four conditions, and hoping you found them all — and your user-facing descriptions still say 55.
As a variable, it lives in one place. Change it once and every bound condition moves together, every description that references it updates, and there is nothing to miss.
Variables are shared across all recommendations in the use case, which is exactly what makes them useful — and worth a moment's thought before you change one, because the change is not local to the rule you are editing.
The fields
| Field | What to put in it |
|---|---|
| Variable Name | The identifier used in conditions and in braces in descriptions. Lowercase with underscores. It is generated for you if you leave it empty and give a label. |
| Label | The human name shown in the condition builder's variable picker and on the chip. Make it read well there - “Clarity threshold”, not “var1”. |
| Type | Whole numbers today. Other types are not yet supported. |
| Value | The number itself. This is the one you will come back and change. |
Setting them up well
- Create the variable before writing the conditions. It then appears in “Bind to variable…” as you build, rather than needing a second pass.
- Name it for the concept, not the rule. “clarity_threshold” serves every rule about clarity; “rule_3_number” serves none of them.
- Reference it in your descriptions. Writing “scored below {clarity_threshold} for clarity” keeps user-facing text honest for free.
- One concept, one variable. Resist a single “threshold” shared by unrelated rules; you will eventually need to move one of them and be unable to.
Delete is blocked while a variable is in use
If any recommendation still references it, deletion is refused and you are shown exactly which rules are using it. Unbind it from those conditions first, then delete.
This is deliberate. A silently deleted variable would leave conditions pointing at nothing - a rule that quietly stops matching is far worse than a blocked delete.
Testing a rule before you save it
You can evaluate a draft rule without saving it - and that matters more than it sounds.
Saving a recommendation publishes it to every user in the subsystem straight away. Before this, that made finding out what a rule matched into a gamble: the only way to see the result was to let everyone else see it too. The Test section removes that trade-off.
It is read-only. It writes nothing, changes no asset, moves nothing through your workflow, and is invisible to end users. Run it as often as you like, including on a rule you have never saved.
It evaluates the draft on your screen - the conditions as you have just edited them, and your variable values as they currently stand, saved or not. So you can move a threshold, test, move it again, and only save once the result is what you wanted.
The verdicts are the real thing
Testing runs the same query the engine runs in production. A condition that passes here passes live. You are not reading an approximation, a sample, or a preview built from separate logic - which is what makes it safe to trust the answer instead of saving to double-check.
Two Modes
Choose the one that matches the question you are actually asking.
| Mode | You give it | You get back | Answers |
|---|---|---|---|
| Single asset | One asset id | A per-condition breakdown of the whole rule | "Why did this one not match?" |
| Scope | Tenants, subsystems, or campaigns | A match count, plus the first ten matching assets with a column per condition | "How much work would this create?" |
Single asset - why this one
Give it an asset id and the rule is shown to you leaf by leaf. For every individual condition you see three things: its verdict, the threshold the rule compared against, and the value the asset actually had.
That last pairing is what makes it useful. A rule that misses an asset you expected it to catch usually fails on exactly one leaf, and this tells you which one and by how much - so you know whether to move a threshold by five points or whether you were testing the wrong field entirely.
Scope - how big is this
Point it at a set of tenants, subsystems, or campaigns and you get the honest size of what the rule would act on, plus the first ten matches laid out with a column per condition.
Read down those columns rather than across. When a rule is too strict, one column is almost always doing all the excluding, and it is visible at a glance which one.
Conditions that can never match are reported separately
A misspelled dimension name, or a workflow state that does not exist in this subsystem, cannot be satisfied by anything, ever.
In a plain count that is indistinguishable from a rule that simply found nothing — the same zero, an entirely different cause. Testing lists these on their own, so you fix a typo instead of spending an afternoon loosening a threshold that was never the problem.
Reading the results
| What you see | What it usually means |
|---|---|
| A condition flagged as unsatisfiable | Fix this first, before anything else. A dimension name or state that does not exist in this subsystem - the rest of the result cannot be trusted until it is corrected. |
| Zero matches, all conditions valid | Too strict - most often a flat AND group that should have been an OR, or a threshold set the wrong side of your actual score distribution. The per-condition columns will show which leaf is doing it. |
| Nearly everything matches | Too loose. The rule will become background noise and get ignored. Tighten the threshold or add a state condition. |
| A plausible count, wrong assets | The right shape on the wrong field. Check you picked the dimension you meant in the second dropdown, then test a single one of those assets to see what it actually compared. |
| Assets that are already finished | Add In last state group is false. |
Reading the count alone is not testing. Test a couple of the individual matches too, and ask whether you would genuinely want this button on them.
Example
Ask authors to clarify ideas that are hard to assess - but only while there is still time to act on them.
- Add the variable first. Name clarity_threshold, label “Clarity threshold”, value 55.
- Title: “{asset_type} is too unclear to assess”.
- Description: “This {asset_type} scored below {clarity_threshold} for clarity, so reviewers cannot judge it yet. Asking the author for detail now avoids a decision based on guesswork.”
- Conditions- an AND group with two rows:
- Score (dimension) · Clarity · ≤ · bound to Clarity threshold AND
- In last state group · is · false.
- Action: Send to clarification. Retitle the button “Ask for more detail”.
- Run the test. Open found matches. If they are genuinely vague and do require clarification, save. If the count is enormous, lower the variable to 45 and run again.
Before you enable: a checklist
| Check | Why it matters |
|---|---|
| You have run the test and opened some matches | The count alone does not tell you the rule is right. |
| The group shape reads correctly in the preview | A flat AND is the most common cause of a rule that never fires. |
| Finished assets are excluded | Nothing annoys reviewers faster than being asked to act on closed work. |
| Thresholds are bound to variables | You will want to tune them, and you will not want to hunt for them. |
| The button says what will happen | It is the only part of your configuration most users ever read. |
| Its priority position is agreed | Position is priority, and it is shared by everyone in the use case. |
Recommendations are configured per use case. A rule written for Ideation applies only to ideas - repeat the setup for each use case you run. Variables are shared within a use case, so a threshold you define for Ideation is available to every Ideation rule, and to none outside it.