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

# Policy Engine

> Configure the workspace default review policy in Acrity.

`Policy Engine` defines the default review policy for the workspace. It controls which review types are active, which additional instructions should guide analysis, and which authors should be included or blocked.

Use `Console > Policy Engine` to configure the workspace default. Use repository settings only for exceptions.

## Who can access

`Policy Engine` requires a Workspace admin (platform admins also have access). Roles are fixed capability sets defined by Acrity, so this access is not configurable per organization.

## When to use

Use this screen to:

* enable or disable review tiers in the workspace;
* add general review instructions;
* define bots that can be reviewed;
* block authors that should not generate reviews;
* view or rotate webhook settings when the screen displays that option;
* align the default policy before connecting many repositories.

## Review tiers

| Tier   | Typical use                                                          |
| ------ | -------------------------------------------------------------------- |
| `Fast` | More direct review for common changes, focused on quick feedback.    |
| `Deep` | More complete review for changes that require more careful analysis. |

The workspace must keep at least one tier active. If both are active, Acrity can apply the configured policy according to review context and product options.

<Note>
  Do not use tiers as a substitute for branch rules. Branch rules should stay in `Console > Repositories`.
</Note>

## Additional instructions

Additional instructions let you adapt review to the organization's standards.

Use them to record guidance such as:

* expected architecture patterns;
* quality criteria relevant to the organization;
* care around testing, security, or compatibility;
* expected language in comments;
* product decisions that should be considered.

Avoid including:

* secrets;
* tokens;
* confidential customer information;
* internal rules that should not appear in review outputs;
* instructions that are too specific to a single repository.

For repository-specific rules, use `Console > Repositories > Detail > Review`.

## Reviewer prompt overrides

Each reviewer role has its own prompt-override field, so you can fine-tune how a specific reviewer analyzes changes across the workspace.

| Reviewer       | Guides                                                       |
| -------------- | ------------------------------------------------------------ |
| Architect      | Structure, design, and how a change fits the broader system. |
| Spec Validator | Alignment between the change and its stated requirements.    |
| QA Engineer    | Test coverage, edge cases, and overall quality.              |

Each field:

* accepts up to 2,000 characters;
* shows whether the current text is a **workspace override** or the **global default**;
* provides a **Revert to global** action that discards the workspace override and restores the global default.

When a field shows the global default, that reviewer uses Acrity's built-in guidance. When you save text into a field, it becomes a workspace override that applies to reviews across the workspace, replacing the global default for that reviewer.

```mermaid theme={null}
flowchart LR
  A[Global default] -->|Save workspace text| B[Workspace override]
  B -->|Revert to global| A
```

<Warning>
  Use reviewer prompt overrides with caution. They change reviewer behavior across the whole workspace, and it is easy to forget an override is in place. For durable, long-lived guidance, prefer committing an `ARCHITECTURE.md` file to the repository so the guidance lives with the code and is versioned alongside it.
</Warning>

## Author policy

Author policy helps control which changes should be reviewed.

| Field           | Purpose                                                      |
| --------------- | ------------------------------------------------------------ |
| Allowed bots    | Identifies automated accounts whose PRs/MRs can be reviewed. |
| Blocked authors | Prevents reviews for specific authors.                       |

Use allowed bots when automations create changes that should receive review, such as dependency updates. Use blocked authors to reduce operational noise or exclude accounts that should not generate analysis.

## Webhook key or URL

Some workspaces can display webhook configuration linked to the review flow.

When the screen displays this option:

* copy the URL only to the correct provider;
* treat the key as a secret;
* rotate the key if exposure is suspected;
* update the provider after rotation;
* validate the webhook through the Console or provider.

<Warning>
  Do not share webhook keys in chats, public tickets, PR/MR comments, or broad internal documentation.
</Warning>

## Configure default policy

<Steps>
  <Step title="Open Policy Engine">
    Go to `Console > Policy Engine`.
  </Step>

  <Step title="Review tiers">
    Enable `Fast`, `Deep`, or both according to the workspace policy.
  </Step>

  <Step title="Add instructions">
    Fill in general additional instructions that apply to most repositories.
  </Step>

  <Step title="Adjust reviewer prompts (optional)">
    Set a workspace override for the Architect, Spec Validator, or QA Engineer reviewer only when needed, and revert to the global default when it is no longer required.
  </Step>

  <Step title="Configure authors">
    Add allowed bots and blocked authors when needed.
  </Step>

  <Step title="Save">
    Save and confirm validation messages.
  </Step>

  <Step title="Test in a repository">
    Choose a representative repository and track the next review in the Ops dashboard to validate the expected behavior.
  </Step>
</Steps>

## Relationship with repository settings

| Level      | Best use                                     |
| ---------- | -------------------------------------------- |
| Workspace  | Default policy for most repositories.        |
| Repository | Exceptions for projects with specific needs. |

Keep the workspace policy simple and stable. This reduces divergence between teams and makes auditing easier.

## Best practices

* Write short, clear, verifiable instructions.
* Avoid duplicating long documentation inside the instructions field.
* Do not include secrets or confidential data.
* Review the policy after major process changes.
* Use repository-level exceptions sparingly.
* Revert reviewer prompt overrides to the global default once they are no longer needed, and keep durable guidance in the repository `ARCHITECTURE.md`.
* Combine author policy with branch rules to reduce noise.

## Common issues

| Symptom                                    | What to check                                                                                              |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| I cannot save                              | Confirm that at least one tier is active and that fields pass screen validation.                           |
| A repository does not follow the default   | Check whether it has its own setting in the Review tab.                                                    |
| Reviews are noisy                          | Review additional instructions, author policy, and repository branch rules.                                |
| A reviewer behaves unexpectedly everywhere | Check whether a workspace prompt override is set for that reviewer and use **Revert to global** if needed. |
| Expected bot was not reviewed              | Confirm that the account is in allowed bots and that the event matches repository rules.                   |
| Author still generates reviews             | Check spelling, provider identifier, and repository configuration.                                         |