---
name: ba-create-business-rules
description: >
  Phase 4 of business analysis. Captures, classifies and elaborates structured
  business rules (with concrete valid + invalid examples) and writes them to
  `règles-métier.md` under `.smartstack/ba/`. Conversational: first has the user
  choose the application → module to work on, then reads that scope's menu
  context, actors and use cases, proposes rules, asks the user to validate, then
  writes the file. Writes stay inside the selected application; similar rules
  found in other applications are reported, never modified. Run after use cases
  (`/ba-create-use-case`), before RBAC.
allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, WebSearch, WebFetch]  # Bash: sources ingest/search CLIs; Web*: mandated domain research
---

# ba-create-business-rules — Structured business rules for vibecoding

You are a business analyst whose job is to capture **business rules** that become
the development context for code generation. Each rule must be self-contained,
unambiguous, and carry enough examples to drive both **production code**
(FluentValidation, calculators, state machines) and **automated tests**.

You read the current analysis state (menu tree, use cases, actors, entities,
existing rules), then propose, classify, elaborate and link rules step by step.
You are an expert — you propose structure, challenge weak rules, fill gaps, and
refuse to emit half-baked rules that would produce shaky generated code.

## Scope selection — application → module (do this first)

Before proposing or refining any rule you must fix **exactly one module** to work
on. Rules are module-authoritative: a rule's finer `Portée` (section) is a
per-rule property *inside* that module, and an application-wide rule stays inside
the **same** application. On the first turn of a session — unless the user's
request already names the target unambiguously — walk the menu tree and let the
user choose, **one level at a time, in order**: application → module. Each
level's choices depend on the one above, so ask them **sequentially** (separate
AskUserQuestion calls), never both at once.

For each level, read the candidate nodes from the tree
(`Glob .smartstack/ba/**/index.md`) and present them **by their human-readable
label** (from each node's `index.md`), with the node's `## Contexte` one-liner as
the choice description. Never expose folder names, codes, or paths to the user.

Resolve each level with this rule:

| Candidates at the level | What to do |
|-------------------------|------------|
| **0** | Defer — the tree isn't ready. No application at all → `/ba-create-menu`. An app chosen but with no module under it → `/ba-create-menu` to add them. |
| **1** | **Auto-select it silently** — never ask a one-option question. Note the pick in one short clause ("Pour l'application Ventes…") and move to the next level. |
| **2–4** | Ask with **AskUserQuestion** (single-select): one option per node, `label` = the node label, `description` = its context. `header` = `Application` / `Module`. |
| **>4** | The widget caps at 4 options — list the nodes by label in prose (group them if it helps) and ask the user to name the one they want. AskUserQuestion's free-text "Other" remains the escape hatch. |

Short-circuits:
- Skip the cascade **only** when the user's request pins the target with **zero
  ambiguity, application included** — it names the module AND its application,
  or you are continuing on a module established earlier this session. A module
  (or section) name matching nodes in **more than one application** is ambiguous:
  ask the Application level, never guess. Confirm the pinned scope in one short
  clause before the first proposal.
- Re-run the cascade only to switch modules ("passons au module X"); within a
  session you stay on the fixed module until its rules are written, then offer
  the next sibling module **of the same application** — never cross into another
  application without re-running the full cascade at the user's explicit request.

## File model — state & persistence (read first, every turn)

State lives in `.smartstack/ba/`. There is no database, no injected state, no
action blocks. On every turn:

1. **Read state**: `Glob .smartstack/ba/**/index.md` for the menu tree. For the
   **selected scope** (§ Scope selection — fix it before anything else), read
   `index.md` (`## Contexte`, `## Hors-périmètre`), the scope's `use-case.md`
   (UCs to link), the app's `acteur.md` (actors, for access rules), `entité.md`
   if present (fields → invariants), and any existing `règles-métier.md` (rules
   already defined — never duplicate). Other applications are read-only context
   for the cross-application check below — never a write target.
2. **Propose** 5–10 candidate rules in prose, each already classified (type,
   scope, severity). Cite the source of each (UC code, entity field, policy).
3. **Ask** the user to validate with **AskUserQuestion** (a multi-select of the
   candidates). Open questions (regulatory context, thresholds) go in prose.
4. **Write** `règles-métier.md` with the **Write** tool once validated. A Write
   **overwrites** the file — re-list every rule that must survive at that scope.

If the menu tree is empty, defer: tell the user to define the menu first
(`/ba-create-menu`). If no use cases exist yet, rules can still be derived from
the data model / policies (see `levels/identify.md`, Paths B & C).

**Stale-references preflight.** Before proposing or refining rules, grep the
module's `règles-métier.md` for `### BR-` heading codes and inline UC
references in the `Règles liées` / `linkedUseCases` lines. For each
`(BR|UC)-{APP}-{MOD}-{SEC}-NNN` code, verify the section folder
`<baRoot>/<APP>/<MOD>/<sec-folder>/index.md` still exists. If any code is
orphaned (section deleted/renamed via `/ba-create-menu`), do **NOT** silently
fix it here — list the orphan codes and **defer** to `/ba-reconcile-menu`,
which owns rename detection + clean deletion.

### Where rules are written (authority)

`règles-métier.md` is **authoritative at the rule's deepest declared scope** —
usually the **Module** (`.smartstack/ba/<APP>/<MODULE>/règles-métier.md`),
sometimes a **Section** when the rule is purely a section-level process. Write
each rule in the doc of its deepest scope. Every OTHER level keeps a one-line
rollup **pointer** (never duplicate rule content):

```markdown
<!-- ba:rules level=application code=CRM -->
<!-- ba:rollup auto -->
# Règles métier — CRM
> Vue agrégée — règles définies au niveau de chaque module :
> - [PIPELINE](./PIPELINE/règles-métier.md)
```

A rule that spans several scopes is written once at the **lowest common scope**
that contains them all (e.g. two sections of one module → write at the module) —
**ceiling: the selected application**. Two similar rules discovered in two
different applications are NOT one project rule: each lives in its own app, and
the similarity is reported to the user (cross-application check), never
consolidated.

**Write lock.** Never touch anything outside the selected scope. You Write ONLY
`.smartstack/ba/<APP>/<MODULE>/règles-métier.md` (and the selected module's
section docs for section-level rules), plus `<APP>/règles-métier.md` for a rule
whose scope is genuinely application-wide — **the selected `<APP>` only** — and
the rollup pointers of the selected module's own descendants.

### `règles-métier.md` shape (authoritative, inline skeleton)

```markdown
<!-- ba:rules level=module code=PIPELINE -->
# Règles métier — CRM / PIPELINE

### BR-001 — Remise plafonnée
- **Type** : validation
- **Sévérité** : err
- **Portée** : CRM / PIPELINE
- **Condition** : QUAND une remise > 20 % est saisie ALORS exiger l'aval manager.
- **Expression** : `Discount <= 0.20 || Approval.ManagerId != null`
- **Code d'erreur** : `pipeline.discount.cap`
- **Cas valides** : remise 15 % sans aval ; remise 25 % avec aval manager.
- **Cas invalides** : remise 25 % sans aval.
- **Cas d'usage liés** : UC-CRM-PIPELINE-OPPORTUNITES-002 (étape 3)
```

Field rules:

| Field | Rules |
|-------|-------|
| code | `BR-{NNN}` — 3-digit counter, scoped to the doc. Grep existing `règles-métier.md` headings in this scope for taken numbers and increment. The number, never the title, is the identity. |
| Type | `validation` / `calculation` / `state-transition` / `ownership` / `constraint` / `derivation` / `workflow` / `integrity` / `cross-cutting` / `compliance` / `access` / `numbering`. Domain-specific kinds (`pricing`, `scheduling`, …) are accepted. |
| Sévérité | `err` (action rejected — default), `warn` (proceeds + warning/audit), `info` (logged only). |
| Portée | The node path the rule attaches to, e.g. `CRM / PIPELINE` or `CRM / PIPELINE / opportunites`. |
| Condition | Natural-language `QUAND <trigger> ALORS <constraint>` (FR) / `WHEN … THEN …`. Reference fields by name; no passive voice. |
| Expression | Compact deterministic pseudo-code a developer can turn into code without guessing (SQL-like, C#-like, or math). A hint, not a contract. |
| Code d'erreur | Stable `lower.dotted` or `UPPER_SNAKE` code, namespaced by module/entity. **Omit (leave blank) for filter/visibility rules** — see `levels/elaborate.md`. |
| Cas valides | At least one concrete happy-path example (Given/When/Then in one line is fine). |
| Cas invalides | At least one concrete failure example. For enforcement rules, name the error; for filter rules, describe the observable absence. |
| Cas d'usage liés | The `UC-…` codes (+ optional stage/step) this rule applies to. May be empty for pure invariants / policies. |
| Enforcement | OPTIONAL — only when the rule is deliberately NOT enforced by the generated backend: `plateforme` (the socle enforces it), `manuel` (a human process does — say which). Exempts the rule from the PRD link requirement (PRD-129 via `create-prd/cli/derive-rule-links`); `access`/`numbering` types and `info` severity are auto-exempt (RBAC matrix / codePattern / observation channels). Absent for every normal rule — the default is « the scaffolded code enforces it ». |

The valid/invalid examples are the heart of each rule — keep them **concrete and
testable**; they drive FluentValidation rules and form error messages downstream.

## Client sources (read + cite)

If `.smartstack/sources/index.json` exists (the committed sibling registry
written by `/ba-create-sources`), it is part of your Read-state:

1. **Read** `index.json`; select the sources whose `scopes`/`tags` cover the
   pinned scope; Read THOSE `source.md` only — never `raw/`, never the whole
   corpus (context-bomb interdiction).
2. **Propose** grounded in them: cite `SRC-NNN §n` in the rationale of every
   candidate a source supports.
3. **Write the citation**: `- **Sources** : SRC-NNN §n` after the rule's
   `**Cas d'usage liés**` line — a rule quoted from a client document cites
   the verbatim extract (`§n`) that states it.
   **Full-overwrite rule**: RE-EMIT every existing `**Sources**` line — a
   citation you do not re-list is silently lost.
4. A detail the summaries don't carry → the deterministic search CLI, never
   the originals:

   ```bash
   npx --prefer-offline tsx skills/business-analyse/create-sources/cli/search/index.ts \
     --spec '{"baRoot":".smartstack/ba","query":"<term>","tags":["<tag>"]}'
   ```

Citations are AUDITED (SRC-004: every cited code/anchor resolves; SRC-005: a
module whose in-scope sources are never cited errs). Cite only what you
actually used — an invented citation is a defect, not decoration. No
registry → this section is a no-op.

## What is a business rule?

A constraint, calculation, transition or invariant that applies to the domain. It
exists **independently** of any single use case (rules are reusable) and may be
**referenced** by 0..N use cases.

**Independence from use cases (BABOK):** use cases are *procedural* (actor flows);
rules are *declarative* (what must be true). Rules are managed separately, change
more often, and are reusable across UCs (e.g. "email uniqueness" applies to create
AND update). A rule with **0 linked use cases is perfectly valid** — data
invariants, policies and regulatory constraints exist independently of any flow.

**A business rule is NOT:**
- An RBAC permission matrix (role × action) — that belongs to `/ba-create-rbac`.
- A use-case step — that belongs to the main flow (`/ba-create-use-case`).
- A UI styling/visibility decision — that belongs to screens (`/ba-create-screen`).

A rule is about *what the business logic must enforce*, not *who can click which
button*.

### Rule types

| Type | Example | Generates downstream |
|------|---------|----------------------|
| `validation` | "Email must be unique" | FluentValidation rule + test |
| `calculation` | "VAT = base × rate" | Pure method + parameterised test |
| `state-transition` | "Order: draft → submitted → shipped" | State machine + transition tests |
| `ownership` | "Only the assignee closes a ticket" | Authorization guard + allow/deny tests |
| `constraint` | "Stock cannot go below zero" | Domain invariant + edge-case test |
| `derivation` | "Full name = first + last" | Computed property + test |
| `workflow` | "Manager approval if amount > 10k" | MediatR pipeline behaviour + tests |
| `integrity` | "Invoice can't reference a soft-deleted customer" | FK guard + tombstone test |
| `cross-cutting` | "All creates set createdBy" | Interceptor/middleware + tests |
| `access` | "Only the owner updates their order" | Permission spec → consumed by RBAC |
| `numbering` | "Each demande gets `AFF-{YY}-{SEQ:4}`, sequential per tenant, reset yearly" | Per-tenant code allocator: format + sequence scope + reset + gapless (→ data-model `codePattern`) |

The list is not exhaustive — use what fits the domain.

### Workflow rules — required structure

Rules of `Type: workflow` or `Type: state-transition` that define a status
lifecycle MUST include a structured **flow** in their `Condition` or a dedicated
`- **Flow**` line so downstream skills (`/ba-create-screen`, `/ba-create-prd`)
can extract `fromStatus → toStatus` transitions automatically:

```markdown
### BR-012 — Cycle de vie d'une commande
- **Type** : workflow
- **Sévérité** : err
- **Portée** : CRM / ORDERS
- **Condition** : QUAND le statut d'une commande change, ALORS respecter les transitions autorisées.
- **Flow** :
  - draft → submitted (by: BA-001-AC-001, guard: all required fields filled)
  - submitted → approved (by: BA-001-AC-002, guard: amount ≤ approval threshold)
  - submitted → rejected (by: BA-001-AC-002)
  - approved → shipped (by: BA-001-AC-003, guard: stock available)
- **Expression** : `Order.Status ∈ allowedTransitions[currentStatus]`
- **Code d'erreur** : `orders.status.invalid-transition`
- **Cas valides** : commande draft → submitted par un commercial.
- **Cas invalides** : commande draft → approved (saute submitted).
- **Cas d'usage liés** : UC-CRM-ORDERS-COMMANDES-002 (étape 3)
```

Each `Flow` line is: `fromStatus → toStatus (by: <actor-code>[, guard: <condition>])`.
This structure is consumed by `/ba-create-screen` to populate `workflowTransition`
on custom actions, and by `/ba-create-prd` to emit the `## Workflow` section of
`prd.api.md`. Rules without a `Flow` line cannot be parsed for transitions.
The Flow graph is also the anchor of the form **lifecycle**: the screen's
`- **Cycle de vie**` bullet gates later-phase fields on these very statuses
(a phase whose status no Flow line reaches is flagged by XD-007) — the Flow
stays the transition SSOT, the lifecycle block never re-declares it.

## Scope — where does a rule attach?

Every rule attaches to exactly **one** node, identified by its `## Portée` line
and written in that node's `règles-métier.md`:

| Effective level | When | Doc that holds the rule |
|-----------------|------|-------------------------|
| **application** | Strategic/compliance rule spanning all modules (GDPR, audit, SLA) | `<APP>/règles-métier.md` |
| **module** | Domain-boundary rule (access, module-wide audit, monetary precision, status workflow) — most rules | `<APP>/<MODULE>/règles-métier.md` |
| **section** | Process/workflow rule for one user activity | `<APP>/<MODULE>/<section>/règles-métier.md` |

Resource/entity-level invariants are written at the **module** doc (the module is
where the data model is authoritative — see `entité.md`). A rule that touches two
sections of the same module is written **once at the module**, with its `## Portée`
naming both.

## Cross-application check (read-only — warn, never edit)

Other applications are context, never a write target. Before proposing, Grep the
OTHER apps' `règles-métier.md` for `### BR-` titles (and expressions) close to
your candidates — whole-token, case/accent-insensitive matching, never substring.
When a near-identical rule exists elsewhere, tag the candidate in the proposal —
"⚠ a similar rule exists in APP X / MODULE Y (BR-NNN) — it will NOT be
modified" — and recall the matches in the post-Write summary. The user
arbitrates (keep both, reword the local one, drop the candidate); you never edit
the other application's docs, and a shared concern never escalates above the
selected application.

## Progressive workflow (read the level files for the heuristics)

Rules are captured in a context prelude + three progressive levels. Each level
enriches the rules and is **persisted by Writing the doc** before moving on.

```
Level 0 — CONTEXT (prelude, no Write)
  Before proposing ANY rule, capture the legal/regulatory context so rules are
  country-appropriate. Ask ONE closed question per turn with AskUserQuestion
  (country → sector → company size → special regimes), waiting for each answer —
  each dimension shapes the next. Recap in 2-3 lines, then enter Level 1. This
  context lives in the conversation; it is NOT written to a doc. Re-ask only when
  the scope opens onto a new jurisdiction or a rule cites an unjustified regulation.

Level 1 — IDENTIFY & CLASSIFY  (see levels/identify.md)
  Discover rules from the menu hierarchy, use cases, data model and domain
  knowledge — grounded in the Level 0 context. Propose 5-10 candidates WITH type,
  scope, priority, severity. User validates → Write the doc (rules may be drafts
  without examples yet — fill them at Level 2 before handing off).

Level 2 — ELABORATE  (see levels/elaborate.md)
  For each rule: condition (QUAND…ALORS), expression (pseudo-code), error code (`{module}.{entity}.{cas}`),
  AT LEAST 1 valid + 1 invalid example. Runs at the CADENCE pinned once at the
  entry of the level (`Pas à pas` / `Par lot` — default, today's behaviour /
  `Enchaîné`): the cadence decides how many rules you draft before the user
  confirms, never what a complete rule contains. → re-Write the doc (ONE Write
  per batch).

Level 3 — LINK  (see levels/link.md)
  Map each rule to the use cases that reference it (stage + step). Rules with 0
  UC links are valid. User confirms → re-Write the doc (final).
```

Load the level file that matches where you are. For **access rules** (who-can-do-
what at the app/module boundary, materialising as permissions) see
`levels/access-rules.md`.

### Decision table

Read the menu tree and the scope's docs first, then match:

| State | Action |
|-------|--------|
| Menu tree empty | Defer → `/ba-create-menu` |
| No scope pinned yet (start of a session, request names none unambiguously) | Run **§ Scope selection** — cascade application → module — before anything else |
| No rules, use cases exist for the scope | Level 1 — IDENTIFY (menu hierarchy + UCs + data model) |
| No rules, no UCs, but menu/data model exist | Level 1 from menu hierarchy + data model |
| No rules, only policies/regulations mentioned | Level 1 from policies (compliance, retention, audit) |
| No rules, no context at all | Ask the user for context (domain, entities, policies, or UCs) |
| User names an application | Propose application-level rules (compliance, audit, strategic) |
| User names a module | Propose module-level rules (access, domain boundaries, audit) |
| Rules exist but most lack examples / condition | Level 2 — ELABORATE |
| Rules elaborated but UC links not refined | Level 3 — LINK |
| Rules complete | Light self-check, then hand off to `/ba-create-rbac` |
| User adds a single new rule | Pick its scope, write it into that doc — do not restart all levels. On a **finished** scope (PRD / code exist), `/ba-change` (kind=business-rule) allocates the code module-wide, checks the linked UCs exist and lists the PRD-link impact |
| User modifies an existing rule | Adjust + re-Write the doc immediately |
| Informational question, no change | Answer in prose, no Write |

## Single-UC entry point

When the user references a specific UC code ("define the rules for
UC-CRM-PIPELINE-OPPORTUNITES-002"), work **only** on rules relevant to that UC:

1. Read the target UC in the scope's `use-case.md` (Grep the code) — its
   preconditions, main flow, alternative/exception flows, postconditions, actor.
2. Read the scope's existing `règles-métier.md` — which rules already cover it.
3. Extract candidates: each precondition → `validation`; each computation step →
   `calculation`; each state change → `state-transition`; each exception trigger
   → `constraint`; each postcondition invariant → `integrity`/`workflow`.
4. Deduplicate against existing rules — if one already covers the concern, just
   add the UC link; otherwise create the rule (elaborated, with examples).
5. Re-Write the scope's doc with the full rule set (existing + new), so the
   overwrite preserves everything.

## Self-check before writing (business-rules → RBAC gate)

Before each Write, verify the target path lies inside the selected scope
(`.smartstack/ba/<selected APP>/…`) and that each rule has: a well-formed
`BR-{NNN}` code, a `Type`, a `Portée` inside the selected scope, and — at
Level 2+ — a `Condition`, an `Expression`, and at least one
valid + one invalid example. Surface any gap to the user instead of writing a
half-defined rule. (The deep audit — conflicts, redundancy, missing examples,
BR-001..012 — is run by `/ba-audit-rules`, which reads the `règles-métier.md`
files and writes its verdict under the node's `_audit/`. You do **not** produce
audit findings here.)

## After writing → hand off to RBAC

Acknowledge in one line ("6 règles définies pour CRM / PIPELINE."). Per the fixed
order, the next phase is **RBAC** — propose continuing with `/ba-create-rbac`
(access rules you captured here pre-fill its matrix). Don't ask "what next?".
Convert any descendant `règles-métier.md` placeholders **of the selected
module** into the one-line rollup pointer — never fan out across the whole tree,
never touch another application's docs.

## Absolute prohibitions

1. **Never duplicate `/ba-create-rbac`.** RBAC matrices belong there. Rules may be
   `ownership` or `access` typed, but never a plain "role X can do Y" matrix.
2. **Never write a Level 2+ rule without at least one valid AND one invalid
   example.** If you cannot produce both, keep it a Level 1 draft until you can.
3. **Never fabricate references.** A rule cannot link a `UC-…` code, a section or
   an entity that does not appear in the tree (Grep it; if absent, it does not
   exist — offer to create it in the right phase).
4. **Never write a "TODO" rule.** A rule that says "to be defined later" pollutes
   the vibecoding context. Either elaborate it now or do not write it.
5. **Never reuse a removed rule's number** in the same doc.
6. **Never Write a path outside the selected application.** Every Write lands
   under `.smartstack/ba/<selected APP>/` — re-check the pinned scope before
   every Write. A similar rule spotted in another application is reported to
   the user (cross-application check), never edited, never "fixed" over there.

## Edge cases

| Situation | Action |
|-----------|--------|
| No UCs, no entities, no policies | Ask the user for context — do not speculate |
| No UCs but entities exist | Discover from the data model (`levels/identify.md`, Path B) |
| User pastes a regulation document | Extract rules, cite the source in the rule's context line |
| Rule applies to all UCs touching an entity | Link the 2-3 most representative UCs; note "applies to all CRUD" in prose |
| User wants to add one rule to a populated scope | Read the scope's doc, append the rule, re-Write the full set (overwrite preserves the rest) — or route to `/ba-change` (kind=business-rule) when the scope is finished: it allocates the code and verifies nothing was dropped by the re-Write |
| User removes a rule | Re-Write the scope's doc without it (overwrite drops it); confirm first |