The .owndiff/ folder
Business rules, knowledge and checks, in Markdown.
.owndiff/ holds what owndiff should know and check. Every Markdown file in it, including subfolders, is read on every review.
.owndiff/
review.md instructions for the main reviewer (fixed name)
billing.md knowledge and rules (any name)
team/
plan-limits.md subfolders only organize files
README.md ignored, for peopleOnly review.md has a fixed name. Without it owndiff uses its default product reviewer. Folder names carry no meaning: the frontmatter decides what a file is.
Knowledge
A file without frontmatter is always part of the main review.
# Billing
Amounts are stored in cents. An issued invoice never changes;
a correction is a new document.Write rules in plain language, the way you would explain them to a new teammate. Keep one topic per file and say why a rule exists when it isn't obvious.
Scoped knowledge
include limits a file to pull requests that touch matching paths.
---
include: ["apps/web/src/onboarding/**"]
---
# Onboarding
A new account always starts on the free plan. The trial starts only
when someone picks a paid plan.User stories
Code shows what the product does, not what it is meant to do. A user story with acceptance criteria tells owndiff the intent. Write it like any other knowledge file:
---
include: ["apps/web/src/invites/**"]
---
# Team invites
As a workspace admin, I invite a teammate by email so they can join
my workspace.
- Only workspace admins can send invites.
- An invite link expires after 7 days.owndiff treats the story as a requirement and each acceptance criterion as a rule. A pull request that works on the story lists it in the summary with how far it is delivered. A change that contradicts a criterion breaks a rule. Stories that already live in a PRD or a stories/ folder need no copy here; owndiff reads them in place.
Checks
check: true also runs the file as a separate, narrow review with its own check run, owndiff / <title>. Each check is a separate model run, so add one only for rules that need it.
---
check: true
include: ["apps/billing/**", "packages/plans/**"]
conclusion: failure
---
# Plan limits
Free: 3 projects, Pro: unlimited, 14-day trial. Any change to limits,
prices or the trial length is a product decision. Flag it unless the
pull request links a recorded decision.Frontmatter
Every field is optional.
| Field | Default | Meaning |
|---|---|---|
title | first heading, then the name | name in the summary and in the check run |
description | first paragraph | one line in the index the reviewer starts from |
include | every change | file globs that make the file relevant |
exclude | none | with include, file globs that never make it relevant |
check | false | true runs a separate check run |
conclusion | neutral | with check: true, failure lets the check block a merge |
conclusion without check: true is an error. An invalid file shows up as a warning with the reason in the pull request summary and the owndiff check run instead of being skipped silently.
Which revision counts
owndiff reads .owndiff/ from the pull request's head, so a new rule applies to the pull request that adds it. A pull request could also weaken the rule it is judged by. Any change to .owndiff/ or owndiff.json is therefore a product decision and never Aligned without a recorded decision.