Proof is in beta, so some details on this page may still change.
.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.
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
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:.”
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.
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”.