# How rules work (/docs/how-rules-work)

The model behind every rule — snapshot, scope, items, checks, diagnostics.



## From a sequence to diagnostics [#from-a-sequence-to-diagnostics]

When PPROLint checks a sequence, it first reads a **snapshot** of it from Premiere: its settings, its video and audio tracks, their clips with their effects, and the sequence markers. Rules only ever see this snapshot. They never read or change your project directly.

Each rule then runs on its own:

1. Its **scope** turns the snapshot into **items**: every clip, every track, every marker, the sequence itself…
2. For each item, its **checks** are tried in order. A check is a **condition** and a **message**.
3. When a condition holds, the item gets a **diagnostic**: the rule's severity, the message with its placeholders filled in, the item it points at and a position in the timeline.

```text
sequence ──snapshot──▶ items of the scope ──conditions──▶ diagnostics
```

A rule is deterministic: the same sequence, the same rule file and the same settings always give the same diagnostics.

## Scope and items [#scope-and-items]

The scope decides what a check is evaluated against, and so which [fields](/docs/reference/fields) it can read:

| Scope      | One item per                      | Fields                                        |
| :--------- | :-------------------------------- | :-------------------------------------------- |
| `sequence` | sequence (once)                   | `sequence.*`                                  |
| `track`    | video track, then audio track     | `track.*`, `sequence.*`                       |
| `clip`     | clip of every track, video first  | `clip.*`, `track.*`, `sequence.*`             |
| `effect`   | user-applied effect of every clip | `effect.*`, `clip.*`, `track.*`, `sequence.*` |
| `marker`   | sequence marker                   | `marker.*`, `sequence.*`                      |

Every scope also reads the rule's options as `options.<name>`. See [Scopes](/docs/reference/scopes) for what each diagnostic points at.

Some built-in rules use a **computed scope**, such as `video-gaps` or `scale-outliers`: PPROLint computes the items for them (a gap between clips, a clip compared with its neighbours) and the rule file keeps the thresholds and messages. You can copy such a built-in rule and change its options, severity and wording; [Computed scopes](/docs/reference/computed-scopes) lists them all with their fields.

## Fields are typed and checked [#fields-are-typed-and-checked]

A field is a named, typed value of the current item: `clip.scale` is a number, `clip.name` a string, `clip.disabled` a boolean. Every field path, operator and placeholder is checked when the rule loads. A typo, or a field the scope does not have, makes the file fail to load with a precise message; it never becomes a rule that silently reports nothing.

Times are integer **ticks**, 254,016,000,000 per second, unless the field's name says frames, seconds or timecode: `clip.duration` is in ticks, `clip.durationFrames` in frames, `clip.startTimecode` a `HH:MM:SS:FF` string.

## Unknown values [#unknown-values]

Some values can be missing from a timeline: an audio clip has no scale, a clip without source media has no media path, an in point may not be set. Such a value is **unknown**. The fields reference marks these fields with a `?` type.

Unknown is never replaced by a default. A comparison on an unknown value is **false**, so a rule does not report what it cannot measure. See [Unknown values](/docs/guides/conditions#unknown-values) for the one trap this sets with `not`.

## One rule, one id [#one-rule-one-id]

The id of a rule (`no-offline-media`) is how the panel, the settings and every diagnostic refer to it. It never changes once a rule is in use; its display `name` may. Two rules cannot share an id, except on purpose: a custom rule file with the id of a built-in rule **replaces** it. See [Custom rules](/docs/guides/custom-rules).

## What a rule file does not do [#what-a-rule-file-does-not-do]

On purpose, the format has:

* **No code.** A rule file combines fields and operators PPROLint knows. It cannot compute anything new, read files or reach the network.
* **No arithmetic or string functions** in conditions. Values a rule needs are fields of their own, such as `clip.durationFrames` next to `clip.duration`.
* **No changes to your project.** Rules report; you decide what to fix.
* **One sequence at a time.** There are no checks across sequences.