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

# Business Flow Checks

> Write your product's business rules in BUSINESS.md so Review flags any change that breaks pricing, entitlement or money rules.

Business flow checks catch the changes that break how your business works: a trial account that reaches a paid feature, a discount applied after tax, a refund that skips approval. You describe the rules once in a `BUSINESS.md` file, and Review checks every pull request (PR) or merge request (MR) against them.

## Why use Business flow checks

* **Catch what a linter can't see.** The code compiles and the tests pass, yet the change gives away a paid feature. Review checks it against your rules.
* **Protect revenue and trust.** Pricing, plans, entitlements, billing and data rules get a reviewer that never forgets them.
* **Act fast.** Each finding names the broken rule, explains the impact and points at the changed line.

## Prerequisites

* A repository connected and enabled in [Review setup](https://docs.cloudthinker.io/guide/code-review/setup.md).
* Permission to commit to the repository's target branch, usually the default branch.

## Turn on Business flow checks

**1. Write a BUSINESS.md**

Describe your product, its modules and the rules each module must keep, in the [file format](#file-format). Start with the two or three rules that would hurt most if they broke.

**2. Commit it to the target branch**

Put the file in the repository root and merge it into the branch your PRs target. There's nothing to switch on in CloudThinker.

**3. Open a pull request**

Open or update a PR that touches code a rule covers. Review checks it against `BUSINESS.md` in the same review.

**4. Read the Business flow finding**

A broken rule shows up as a Business flow finding: a Review comment on the changed line. It explains what breaks and why it matters, and carries a **Business rule:** line with the ID it cites.

**Success state:** the cited ID matches a rule or entry in your `BUSINESS.md`.

> [!TIP]
>
> Business flow works hand in hand with [Codebase Atlas](https://docs.cloudthinker.io/guide/code-review/codebase-atlas.md). Atlas maps your codebase's architecture and your product's business flows, so Review checks business rules even before you write a `BUSINESS.md`. Add the file when you want to set the exact rules yourself: it always comes first.

## How it works

1. **Read the rules.** Review reads `BUSINESS.md` from the target branch.
2. **Match the change.** It finds the rules that cover the code this change touches.
3. **Check each rule.** It reads the change and the code around it against those rules.
4. **Report.** For each broken rule, it posts a finding that cites the rule, with a severity that matches the impact.

A PR that edits `BUSINESS.md` is reviewed against the current rules. Its new rules apply once it merges.

## File format

`BUSINESS.md` has a fixed shape, so Review can cite each rule by its ID:

* The first line is `# Business map: <owner>/<repo>`.
* Then a `## Product` section, a `## Modules` section and an optional `## Flows` section, in that order.
* Each entry is a `### <id>: <title>` heading, a short description, and the optional lines below.

| Line | Format | What it's for |
| - | - | - |
| `Code roots:` | Paths in backticks, separated by commas | The files and folders this entry covers |
| `Depends on:` | Entry IDs, separated by commas | Other entries this one relies on |
| `Sources:` | Free text, items separated by `; ` | Where the description comes from, such as `README.md` |
| `Invariant <id>: <rule>` | One line per rule | A rule the code must keep. Review cites its ID |

IDs are lowercase, dot-separated and unique. The first part names the section: `product.`, `modules.` or `flows.` for entries, and `invariants.` for rules. After it, use lowercase letters, digits and hyphens, as in `invariants.plans.trial-fast-only`.

```markdown theme={null}
# Business map: acme/meterly

## Product

### product.meterly: Meterly
Usage-based billing for API teams.

## Modules

### modules.plans: Plans
Decides which run types each plan can start.
Sources: README.md
Code roots: `src/plans/`
Invariant invariants.plans.trial-fast-only: A Trial workspace starts only Fast runs.

### modules.invoicing: Invoicing
Builds the monthly invoice from metered usage.
Code roots: `src/invoicing/`
Invariant invariants.invoicing.tax-after-discount: Tax is computed on the amount after discounts.

## Flows

### flows.upgrade: Upgrade a trial
A Trial workspace moves to a paid plan and unlocks Advanced runs.
Code roots: `src/billing/upgrade.py`
Depends on: modules.plans, modules.invoicing
Invariant invariants.upgrade.paid-before-advanced: Advanced runs unlock only after the first payment succeeds.
```

> [!TIP]
>
> Write each rule as one sentence a reviewer can test a change against. Give every module a `Code roots:` line, so Review knows which files its rules cover. Keep the file under 200 KB, with one product entry, at most 12 entries per section and at most 20 rules per entry.

## Troubleshooting

> [accordion] No Business flow findings appear
>
> Check that `BUSINESS.md` is in the repository root on the PR's target branch, and that each module has a `Code roots:` line. A PR that adds the file uses it from the next review after it merges. When no rule is broken, there's nothing to report: a quiet PR is good news.

> [accordion] Review skips BUSINESS.md
>
> Review skips a file that doesn't follow the format, and the rest of the review still runs. Check for:
>
> * A first line other than `# Business map: <owner>/<repo>`.
> * Text or a `#` or `##` heading outside the three sections, or sections out of order.
> * An ID that repeats, starts with the wrong section name, or has capitals or spaces.
> * A `Depends on:` ID that isn't in the file, or a code root that starts with `/` or contains `..`.
> * A file over the size and entry limits in the tip above.
>
> Fix the file and merge it. The next review uses it.

> [accordion] A finding cites the wrong rule
>
> Narrow each `Code roots:` line to the files that entry owns, and rewrite a vague rule as one clear sentence.

## Related

> [card] [Learnings](https://docs.cloudthinker.io/guide/code-review/learnings.md)
>
> Add your team's conventions and see the rules Review learned

> [card] [Codebase Atlas](https://docs.cloudthinker.io/guide/code-review/codebase-atlas.md)
>
> See your architecture and business flows on one map

> [card] [Review workspace](https://docs.cloudthinker.io/guide/code-review/review-workspace.md)
>
> Triage and resolve findings across your PRs

> [card] [Mention commands](https://docs.cloudthinker.io/guide/code-review/mention-commands.md)
>
> Ask for a fresh review after you change your rules


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