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

# Proof rules

> Use .blacksmith/PROOF.md to decide which pull requests Proof runs on automatically.

> [!NOTE]
>
> Proof rules are rolling out to organizations in the Proof private beta.

When Proof runs automatically, \[code]smith decides for each pull request whether a run is worth it. A `.blacksmith/PROOF.md` file in your repository gives that decision your own rules: skip infrastructure changes, never run on dependency bumps, always run on billing code.

## How automatic Proof decides

With Proof set to **Drafts and ready PRs** or **Ready PRs only**, \[code]smith makes a decision when a pull request opens, when it is marked ready for review, and when new commits are pushed. **Ready PRs only** skips draft pull requests before any decision is made.

Once Proof has run on a pull request, a later push that only rebases, reformats, or changes generated files since that run is skipped before your rules are read.

Without a `PROOF.md`, \[code]smith's default policy applies.

## Add a PROOF.md

Create `.blacksmith/PROOF.md` at the root of your repository and merge it into the branch your pull requests target:

```markdown .blacksmith/PROOF.md theme={"system"}
Never run Proof for changes under `infra/**` or `terraform/**`.
Always run Proof for changes under `services/billing/**`.
```

Write rules in plain language. Markdown headings and lists are fine.

### Examples

Example

## What a rule can refer to

Rules work best when they point at something visible on the pull request. For example:

* **Paths:** "Never run Proof for changes under `infra/**`."
* **Labels:** "Skip any pull request labeled `no-proof`."
* **Branches:** "Skip pull requests from branches starting with `renovate/`."
* **Target branch:** "Only run Proof on pull requests that target `main`."
* **Drafts:** "Do not run Proof on draft pull requests."
* **Titles:** "Skip pull requests whose title starts with `chore:`."

`PROOF.md` is not a strict pattern matcher. A model reads your rules alongside the pull request and decides. Clear, specific rules give consistent results:

* Name exact paths, branch prefixes, and labels: `` `infra/**` ``, `` `renovate/` ``, `` `no-proof` ``.
* Write one rule per line or list item.
* Say what should happen: "Never run Proof" or "Always run Proof".
* When rules overlap, state which wins.

Vague guidance such as "be conservative" is followed loosely. Notes on how Proof should test, such as login details, do not belong in this file and do not affect the decision.

## Defaults and limits

| Situation | What happens |
| - | - |
| No `PROOF.md`, an empty file, or a file \[code]smith cannot read | \[code]smith's default policy applies. |
| `PROOF.md` longer than 20,000 characters | Only the first 20,000 characters are used, cut at the last full line. |
| Long pull request descriptions and commit histories | Descriptions are cut at 4,000 characters. Only the last 30 commit messages are read, each cut at 300 characters. |
| You request Proof yourself | Proof runs. Rules only filter automatic runs. |

Requesting Proof yourself includes commenting `@codesmith prove it` on a pull request, clicking **Prove this works** in the pull request footer, and asking \[code]smith to prove a pull request in a session.

When a rule decides the skip, the session thread usually labels it "ruled out by .blacksmith/PROOF.md". The label is the main reason the model gives, so a skip a rule caused can occasionally show another reason, such as "docs-only change".


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