Business Rules
The Business Rules page of a project: the decisions of the business the system must honour, each with its kind, statement, condition and action, exceptions, worked examples, authority, priority, dates in force, status and owner, its review lifecycle and its versions.
By the end of this page you will have written down the decisions of the business a project's system must honour as rules a developer can code and a tester can check, know every field a rule carries and what reads it downstream, and know how a rule moves from a draft to a baseline, how it is deleted, and where every version of it is kept.
A business rule is a decision of the business, not of the software: a member whose spend
over the last twelve months reaches 5,000 is a platinum member. It is written in plain words
with the condition it fires on and what follows, the exceptions, worked examples of an input and
what is expected, who has the authority to change it and the dates it is in force. Rules number
on their own sequence (CRM-BR-7) whatever their kind, so a rule and a requirement never share a
key, and every save of one is kept as a version, examples
included. Requirements say what the system shall do; rules say what the business has decided,
and the same rule is read by every requirement, story and test that touches it.
Before you begin
| You want to | You need |
|---|---|
| Open the Business Rules page | business-rule:view-any on the project, which every default role carries. A client guest sees the agreed rules only. |
| Add a rule | business-rule:create. Project managers and business analysts have it by default. |
| Edit or move a rule | business-rule:update. |
| Delete a rule | business-rule:delete. |
| Name an owner | The person to be a member of the team. |
| Name an authority | The stakeholder to be on the project's stakeholder list. |
The page lives under a project: open the project and choose Business Rules in the sidebar, badged with how many rules you may see.
Read the rules
The table lists one rule per row:
| Column | What it shows |
|---|---|
| Reference | The rule's key, painted in the colour of its kind. |
| Rule | The name, with the first line of the statement beneath it. Press the name to open the detail flyout. |
| Kind | Constraint, derivation, computation, inference, action enabler or policy, with the kind's icon. |
| Status | Draft, in review, approved, baselined or deprecated, as a badge. Hidden from a guest. |
| Priority | The MoSCoW letter: M, S, C or W. |
| Owner | The person who answers for the rule, or Unassigned. |
| In Force | The dates the rule applies between, Always when none, Open-ended when it has no end. |
| Updated | How long ago the record last changed. |
| Row menu | View Rule, Edit Rule, Move to, Activity, Delete Rule. |
Sort by reference, name, kind, status, priority, the start date or updated by pressing a column heading; press it again to flip the direction. The list opens in the project's own order.
Above the table, narrow the list with the search box (words in the reference, the name or the authority), the kind, status and priority lists. The filters travel in the page address, so a filtered list can be shared; Clear Filters on the empty state drops them all.
Add a rule
- Press New Rule.
- Pick the Kind and the Priority. A constraint is the default; the kind says how the rule is read, tested and coded.
- Type the Name and the Statement: what the rule is called and the rule in plain words, as the business would say it. These two are enough; Heimdall will propose the rest.
- Write When the rule applies and Then what follows, each in one line, and the Exceptions.
- Under Worked examples, press Add Example and type an input and what the rule gives for it; add one for the boundary and one for an exception.
- Under Authority and dates, pick the Stakeholder who may change the rule, type the Authority it rests on and set the dates it is In Force.
- Pick the Owner and press Create Rule.
The rule takes the next number of the rules' sequence (the first rule of CRM is CRM-BR-1),
starts as a draft, appears in the table at once, writes its first version with its examples
inside it, and business_rule.created goes out to every endpoint subscribed to it.
A rule without an example is argued about
Platinum from 5,000 reads clear until someone asks about 4,999.99, about a refund, or about the day the threshold is crossed. Three examples, one at the boundary and one for an exception, settle the argument before the code is written, and the test generator will turn each one into a case.
Open a rule
Press a rule's name, or View Rule in its row menu, to open the detail flyout: the reference, kind, status and priority at the top, the name, then the statement, the condition and the action side by side, the exceptions, the worked examples in order, the stakeholder and the authority, the dates in force, the owner, the dates, and the Versions section with every save of the rule. From the flyout:
- Edit opens the editor on this rule.
- Move to changes the status in one step, offering only the moves the lifecycle allows.
- Restore this version under any earlier version puts it back, examples included; see revisions and versions.
- Activity opens the rule's history: every change, who made it and where it came from.
- Delete opens the confirmation.
A link such as /projects/<id>/rules?show=<rule id> opens the page with that rule's flyout
already open; Heimdall's View buttons use it.
Edit a rule
- Press Edit Rule in the row menu, or Edit in the flyout.
- Change what you need, the example rows included: Add Example appends a row, the arrows reorder the rows and the cross removes one. The owner must be a member of the team, the stakeholder one of the project's, and the end date on or after the start.
- Press Save Changes.
The save writes a new version of the rule, examples included, and business_rule.updated goes
out with the columns that changed, each with its old and new value. An edit that changes nothing
writes nothing and announces nothing. The status does not change from the editor; it moves from
the list or the flyout.
Move a rule along its lifecycle
A rule reaches In review and Approved through its approval alone, the same way a requirement does: Submit for review on the approval bar puts it in review, and the approvers' verdicts move it out, to approved when the request carries and back to where it stood when it is rejected or withdrawn. Move to in the row menu or the flyout offers the other moves the lifecycle allows from where the rule stands, and is refused while a request is open:
| From | To |
|---|---|
| Draft | Deprecated |
| In review | Draft, deprecated |
| Approved | Baselined, deprecated |
| Baselined | Deprecated |
| Deprecated | Draft |
An approval stamps when the rule was agreed and at which version, and a client guest sees it from
that moment on, through baselined, and loses it when it is deprecated. Every move writes a version
with the reason moved and business_rule.status_changed goes out with the status before and
after; an approval writes one with the reason approval.
Baselined is the freeze's badge
A baseline that holds an approved rule moves it to baselined when the baseline is frozen and locks it: the editor, the status menu and the restore button refuse, naming the baseline, until an approved change request unlocks it, which returns it to approved. The status menu still offers the move to baselined by hand, for a scope agreed outside the application; that badge carries no lock.
Delete a rule
Delete Rule in the row menu or Delete in the flyout opens the confirmation. Deleting
removes the rule with every version it kept and its activity history; its number is never handed
out again. business_rule.deleted goes out. Prefer Deprecated for a rule the business
withdrew: it keeps the record and the reasoning.
All the fields
What happens next
- Every save, move and restore writes a version, examples included, and an entry in the project's activity history.
business_rule.created,business_rule.updated,business_rule.status_changed,business_rule.restoredandbusiness_rule.deletedgo out to the webhook endpoints subscribed to thebusiness_rule.*family.- Requirements, stories, data entities and test cases will link to rules, the quality review will flag a story that contradicts a rule, and the test generator will draft one case per example, as those modules land.
Heimdall on this page
Quality in the flyout asks Heimdall to read the rule for its condition, action, exceptions, worked examples and authority, and for conflicts and overlaps with every other rule of the project, and to score it out of 100 with the findings to fix. See Quality review.
Heimdall reads rules and their versions through the same tools the MCP server offers, proposes rules as drafts a person reviews when a story or a requirement implies one, and carries the open project as its context.
On the editor, Ask Heimdall beside each long field drafts it, improves it, shortens it, makes it testable or rewrites it as Given, When, Then; the draft waits under the field until you take it or drop it. See inline assists.
The brief import will draft whole rulebooks into a review queue, and the quality review will keep asking for an example until each rule has one.
From the API and MCP
Business Rules API
List, read, add, change, move and delete rules, and read and restore their versions.
Planning tools
list_business_rules, get_business_rule and propose_business_rule: the MCP tools that read and propose rules.
Permissions
| Action | Permission |
|---|---|
| See the rules | business-rule:view-any, business-rule:view; a client guest sees the agreed rules only |
| Add a rule | business-rule:create |
| Edit or move a rule | business-rule:update |
| Delete a rule | business-rule:delete |
| Read or restore its versions | business-rule:view to read, business-rule:update to restore; never a client guest |
Frequently asked
Related
- Quality review — the Quality panel in the flyout: Heimdall's score and findings, and the badge on the row
- Traceability — the Links panel in the flyout: what this implements, verifies, depends on or relates to, read from either side
- Comments and mentions — the Discussion panel in the flyout: questions, answers, mentions, followers
- Attachments — the Files panel in the flyout: wireframes, specifications and samples pinned on the record
- Functional requirements — what the system shall do, which the rules constrain
- Revisions and versions — every save kept, any version put back
- Status reference — every kind, status and priority
business_rule.*webhook events
How is this guide?
Last updated on
Non-Functional Requirements
The qualities a system shall keep: each non-functional requirement with the category it belongs to and the measure that says when it is met, the categories, how to write a target and what reads them.
Quality review
Heimdall reads a story, a requirement or a business rule against INVEST, clear wording, testability, the project's business rules and its siblings, scores it out of 100 and lists what to fix; nothing changes until you do.