> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rootly.com/llms.txt
> Use this file to discover all available pages before exploring further.
# AI SRE Investigation Rules
> Match Rootly alerts by fields or payload values, control automatic investigations, and add alert-specific AI SRE guidance.
Investigation rules decide which alerts Rootly AI SRE investigates automatically and which alert-specific instructions it applies to manual or automatic runs.
Rules apply to alerts. Start an investigation on a non-maintenance incident from its **AI SRE** tab.
## Create A Rule
Configure a rule and preview it against your recent alerts before saving.
With an Incident Response seat, open **AI & Agents → AI SRE → Investigation rules**. An eligible admin without that seat can open the direct rules surface by appending `/account/ai/surfaces/investigation_rules` to the Rootly app URL.
Select **New rule**, then enter a name that identifies the alert class, such as `Critical checkout alerts`.
Select the alert fields, operators, and values the rule should match. All conditions must match. Leave the condition list empty to match every alert.
Use the per-condition and combined counts to check the last 90 days. Open the matching-alert list to inspect the alerts behind a count.
Optionally add guidance for this alert class, such as the service-specific signal or deploy source AI SRE should check.
Select **Manual**, **Auto-run**, or **Paused**. Optionally set a cooldown to limit how often this rule can start automatic investigations, then select **Save**.
Incident Response Owners and Admins, and On-Call Admins, can create and manage investigation rules after your Rootly account team enables AI SRE for the current team. This rule surface does not require an Incident Response seat, but admins without that seat must use the direct path above because the broader **AI & Agents** configuration area remains seat-gated. See [Manage User Permissions](/managing-users/user-permissions#ai-agents-and-ai-sre) for the canonical matrix. Contact your Rootly representative to disable AI SRE; the self-service global AI opt-in is not its kill switch.
## Rule Settings
A recognizable label for the alert class. Use a name that distinguishes the rule from other rules in the list.
Alert fields and values that must all match. Values within one condition match any selected value. An empty condition list applies the rule to every alert.
Guidance added to investigations of matching alerts, including manual runs. Instructions guide the investigation but don't count as evidence.
Controls whether matching alerts run automatically, wait for a manual start, or ignore this rule.
After this rule successfully starts an automatic investigation, prevent the same rule from starting another until the cooldown expires. Leave it blank or enter `0` to disable the cooldown. The value must be a whole number from `0` through `2147483647`.
## Condition Fields
| Field | What It Matches |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Title** | The alert title |
| **Description** | The alert description |
| **Urgency** | One or more configured alert urgencies |
| **Source** | One or more alert sources already present in Rootly |
| **Status** | Rootly's stored alert states: Triggered (`triggered`), Acknowledged (`acknowledged`), Resolved (`resolved`), Non-Paging (the UI label for the full `open` state), or Deferred (`deferred`, used when a deferral path delays paging). Selecting **Non-Paging** matches every `open` alert, including alerts returned to `open` because a paging attempt could not notify a target—not only alerts that never paged. |
| **Group status** | Leader, Member, or Standalone alerts |
| **Custom field** | Values from one of your alert custom fields |
| **Payload** | A value at a payload path such as `details.region` |
Text, custom-field, and payload conditions support these operators:
* **is one of** matches an exact value without case sensitivity.
* **contains one of** matches when the field contains a selected value without case sensitivity.
* **is not one of** excludes the selected exact values.
Urgency, source, status, and group status support **is one of** and **is not one of**.
Start with stable fields such as urgency, source, and a service custom field. Use payload paths when the alert source sends a reliable field that Rootly doesn't normalize elsewhere.
## Run Modes
| Mode | Matching Alert Behavior | Rule Instructions |
| ------------ | --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| **Manual** | AI SRE waits for a responder to select **Start investigation** | Applied to a matching manual investigation |
| **Auto-run** | AI SRE starts when a new alert matches the rule | Applied to the automatic investigation and a matching manual investigation |
| **Paused** | The rule neither starts an investigation nor contributes instructions | Not applied |
An automatic investigation runs once for an alert. If an investigation is already pending or running, another matching trigger doesn't start a duplicate run. A positive cooldown also suppresses automatic starts for other alerts matched by that rule until the rule's cooldown expires. Manual investigations remain available.
An automatic run has no initiating responder. It uses the Rootly AI SRE background identity, the team's configured connector credentials and tool allowlists, and—when enabled—registered Private Agent capabilities authorized for the `ai-sre` system actor. This is **not** a read-only guarantee. A Rootly-reviewed built-in connector tool can accept a provider-defined command or query language that changes data when provider-side controls allow it. Custom MCP and Private Agent can also expose write-capable operations.
For **Auto-run** rules, allow only built-in connector capabilities and provider commands, Custom MCP tools, Private Agent capabilities and local policies, and provider credentials that are safe for unattended use without an interactive approval pause.
## How Overlapping Rules Behave
More than one rule can match the same alert. AI SRE handles the overlap in two parts:
* **Starting the run:** the matching **Auto-run** rule with the lowest stored position controls the automatic start and its cooldown.
* **Applying instructions:** the matching non-paused rule with the lowest stored position contributes its rule instructions.
Rootly appends each new rule to the bottom of the stored priority list. As a result, the oldest remaining rule normally has the lowest position and wins when multiple rules match. Editing a rule or sorting the rules table by name, status, or creation date doesn't change its priority. Manual reordering isn't currently available in the rules UI.
Create mutually exclusive conditions when overlapping rules would give different guidance, or keep their instructions compatible. Don't use the table's current sort order to resolve an overlap.
An empty-condition **Auto-run** rule matches every alert. Check the 90-day preview before saving it to avoid starting investigations for noisy or low-value alerts.
## Design Reliable Rules
* Start in **Manual** mode and compare the preview with the alert class you intended to match.
* Use **Auto-run** for alerts with a clear owner and enough connected evidence to investigate.
* Add a cooldown when a noisy alert class can create many distinct alerts in a short period. A cooldown is shared by every alert matched by that rule.
* Keep rule instructions scoped to the matched alert class. Put shared guidance in [AI SRE instructions](/ai/ai-sre/instructions).
* Prefer stable normalized fields over free-form title text when both are available.
* Pause a rule while changing an alert source or payload contract.
* Review the seven-day alert count in the rule list for unexpected growth or inactivity.
## Troubleshooting
Open the rule and inspect the 90-day count for each condition and for all conditions together. Add a stable discriminator such as source, urgency, or a service custom field. Values inside one condition use any-match behavior; separate conditions use all-match behavior.
Confirm the rule is in **Auto-run** mode and that the alert matches every condition. Check the payload path and value casing in the matching-alert preview, whether a higher-priority matching Auto-run rule is selected, and whether that rule's cooldown is still active. AI SRE also needs to be enabled for the current team.
Another non-paused rule with a lower stored position may also match the alert. The rules table's sort order doesn't change priority, and manual reordering isn't currently available. Make rules with different instructions mutually exclusive, or pause the broader rule while you refine its conditions.
## Frequently Asked Questions
Yes. The matching non-paused rule with the lowest stored position contributes its instructions to manual and automatic alert investigations.
No. Investigation rules match alerts. Start AI SRE manually from the **AI SRE** tab on a non-maintenance incident.
It matches every alert. In **Manual** mode it supplies default rule instructions; in **Auto-run** mode it starts an investigation for every new alert.