# The .owndiff/ folder (https://docs.owndiff.com/configuration/owndiff-folder)

`.owndiff/` holds what owndiff should know and check. Every Markdown file in it, including subfolders, is read on every review.

```text
.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 people
```

Only `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 [#knowledge]

A file without frontmatter is always part of the main review.

```md title=".owndiff/billing.md"
# 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 [#scoped-knowledge]

`include` limits a file to pull requests that touch matching paths.

```md title=".owndiff/onboarding.md"
---
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 [#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:

```md title=".owndiff/invites.md"
---
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 [#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.

```md title=".owndiff/team/plan-limits.md"
---
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 [#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 [#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.