Skip to main content
Proof is in beta, so some details on this page may still change.
Proof can run on its own when a PR opens or gets new commits. Before it does, Proof decides whether that PR is worth a run. .blacksmith/PROOF.md is where you tell it how: skip infra, don’t bother with dependency bumps, always run on billing code. If Proof is set to When I ask, it never runs on its own, so these rules don’t do anything.

How automatic Proof decides

Proof makes the call when a PR opens, is reopened, gets marked ready for review, and on every push. A few things get settled before your rules come into it:
  • On Ready PRs only, drafts are skipped outright.
  • Once Proof has run on a PR, a push that only rebases, reformats, touches generated files, or changes nothing is skipped.
  • A push while Proof is running joins that run instead of starting a new one.
  • A PR that changes more than 200 files always runs. Rules aren’t read.
Everything else is decided with your rules. Re-runs on pushes are usually most of a repo’s Proof usage, so that’s where rules pay off. No PROOF.md? The default is to run on anything that changes code that runs (UI, backend, scripts, config, dependencies, migrations, even small refactors) and skip PRs that only touch tests, docs, CI or formatting.

Add a PROOF.md

Create .blacksmith/PROOF.md at the root of your repository and merge it into the branch your pull requests target. Proof reads it from that branch, so a PR can’t change its own rules.
.blacksmith/PROOF.md
Write it like you’d explain it to a teammate. Headings and lists are fine.

Examples

What a rule can refer to

Rules work best when they point at something you can see on the pull request:
  • Paths: “Never run Proof when every changed file is 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:.”
Heads up: PROOF.md isn’t a pattern matcher. A model reads your rules next to the pull request and makes a call. Specific rules get consistent results:
  • Name exact paths, branch prefixes and labels: `infra/**`, `renovate/`, `no-proof`.
  • One rule per line or list item.
  • Say what should happen: “Never run Proof” or “Always run Proof”.
  • When rules overlap, say which wins.
“Be conservative” gets followed loosely, at best. Rules see the whole pull request, not just the latest push. “Never run Proof for changes under infra/**” can skip a PR that changes infra/** and your app. If you mean “only infra,” write “when every changed file is under infra/**.” This file only decides whether Proof runs. How Proof should test (login steps, seed data, test accounts) goes in your setup docs and saved secrets.

Defaults and limits

Asking yourself means commenting @codesmith prove it, clicking the Proof button in the PR description (when your org has Edit PR descriptions turned on in [code]smith settings), or asking [code]smith in a session. When a rule causes a skip, the session thread usually says “ruled out by .blacksmith/PROOF.md”. That label is the main reason the model gave, so now and then a rule-driven skip shows something else, like “docs-only change”.