> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ironoctopus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Change a rule

> How to change a built-in rule for your workspace or one project: where rules live, how inheritance works, and how to publish, test and roll back a change.

Every rule described in [built-in rules](https://docs.ironoctopus.ai/rules/built-in-rules.md) can be changed by a workspace **Owner** or **Admin**. A change applies to future decisions only. It never re-reviews or re-approves work that's already done.

## Where rules live

| Level | Where | Applies to |
| - | - | - |
| Platform defaults | Built in. | Every project, until something more specific replaces it. |
| Workspace | Workspace settings › **Runbooks** | Every project in the workspace. |
| Project | Project settings › **Runbooks** | That project only. |

### How inheritance works

When a decision is made, Iron Octopus uses the first matching active policy, from most to least specific:

1. A workspace policy that **prevents matching project overrides**.
2. The project's own policy.
3. The workspace policy.
4. The platform default.

**What happens now**, at the top of each runbook page, shows the policy actually in force and where it comes from. Members and Guests can read it, but only Owners and Admins can change it.

## Change a work-item rule

Use this for review, confidence thresholds, rework and what needs a person.

**1. Open the runbook**

Go to Workspace settings › **Runbooks**, or to the project's settings › **Runbooks** for one project. Choose **Work-item runbooks**.

**2. Choose which work it applies to**

Give the policy a **Policy name** that administrators will recognize in the audit history. Under **Apply this policy to**, choose all work-item types, or only Coding, Bug-fix, DevOps or Planning items. **Coding items** is the safest default for code-review rules.

**3. Choose the review outcome**

Choose **Autonomous AI Worker review** or **No code review**. Then set the **Maximum risk tier eligible for automatic approval**, the confidence minimum for each risk level, and what happens when a required criterion is unverifiable, blocked or not applicable: **Require human review** or **Allow runbook approval**.

**4. Decide whether projects can override it**

At workspace level, turn on **Prevent matching project overrides** only when every project must follow this policy.

**5. Give a reason and apply**

Enter a **Reason for this change**, then click **Save, publish, and activate**. Iron Octopus saves, validates, publishes and activates the policy in one step. To prepare a change without applying it, click **Save without activating**.

## Change a feature rule

Use this for approvals, automatic moves, dependencies, merge on release and waivers.

**1. Open the runbook**

Go to **Runbooks** in workspace or project settings, and choose **Feature runbooks**.

**2. Name it and choose the feature type**

Under **Runbook identity**, set the **Policy name** and the **Feature type** it governs: **All Feature types**, **Build**, **Maintenance** or **Bug fix**.

**3. Configure each gate in order**

Expand **Planning → Building**, **Building → Acceptance** and **Acceptance → Released**. For each gate, choose how it completes:

* **Automatic** completes as soon as every requirement passes.
* **Human decision** shows the evaluated requirements to a person, who decides.

Under **Transition requirements**, you can add a **work-item requirement**, such as a percentage of work items Done, or a **prompt requirement**, where a configured assessment must pass.

**4. Set the other rules**

Choose whether a dependency must be **Released (default)** or **Acceptance cleared**. Set **Require automatic merge before release** and **Allow audited assessment and defect waivers**.

**5. Save, test and publish**

Enter a **Reason for change** and click **Save draft**. To see what the draft would decide, use **Preview and explanation**: enter a Feature ID and a requested stage. The preview doesn't change the feature. When you're ready, click **Validate, publish & activate**.

## Versions and rollback

Every published policy is a numbered version that can't be edited.

* **Compare versions** shows exactly what changed between two versions.
* **Roll back to this** reactivates an earlier version without rewriting history.
* **Retire** takes a version out of use. A reason is required.
* **Use inherited runbook** removes a project's own policy, so the workspace policy applies again.

Every change records who made it, when and why. **Audit history** shows the full trail.

## If a change won't apply

| You see | Why | What to do |
| - | - | - |
| **Workspace policy takes precedence** | The workspace prevents project overrides for this policy. | Save the project policy as a draft, or ask an admin to change the workspace policy. |
| **Confidence thresholds must be whole numbers from 0–100 and cannot decrease as risk increases.** | A higher risk level has a lower threshold than a lower one. | Make each threshold at least as high as the one below it. |
| **Explain why this policy is being changed before applying it.** | The reason is empty. | Enter a reason. Every change needs one. |
| **The runbook did not pass validation.** | The configuration is incomplete or contradictory. | Read **Definition diagnostics**, fix the configuration and try again. |
| **Assessments run in Acceptance.** | A prompt requirement is on the wrong gate. | Move it to **Acceptance → Released**. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.