---
name: ba-modeling-detail
description: >
  Pass 2 of the optional Two-Pass fast-modeling path. Take a SINGLE inventory
  item flagged `moderate` or `complex` (from a scope's `_inventory.md`) and
  expand it into a fully-detailed use case (Cockburn flows, pre/postconditions)
  or business rule (expression + concrete valid/invalid examples), then write it
  into the authoritative doc (`use-case.md` for a UC at its section,
  `règles-métier.md` for a rule at its scope) under `.smartstack/ba/`. Reads the
  inventory + the authoritative doc + `acteur.md`; writes by appending/Editing
  the doc while preserving every existing item.
allowed-tools: [Read, Write, Edit, Glob, Grep, Bash]  # Bash: sources-search CLI (client sources)
---

# ba-modeling-detail — expand one inventory item to full detail (Pass 2 of 2)

This is **Pass 2 of the optional two-pass fast-modeling path**. Pass 1
(`/ba-modeling-inventory`) emitted a lightweight `_inventory.md` listing every
use case and business rule of a scope, each flagged `simple | moderate |
complex`. Your job here is the inverse of breadth: take **one** item flagged
`moderate` or `complex` and expand it into a complete specification, then write
it into the authoritative doc. Items flagged `simple` skip this pass — they are
already detailed enough for the inventory to stand.

You produce the **same doc shapes** as the canonical definer skills
(`/ba-create-use-case` for UCs, `/ba-create-business-rules` for rules); this
skill is just the single-item, inventory-driven entry point into them. Match
their field names, code formats and self-check exactly — see
`_workflow/doc-templates.md` for the authoritative skeletons.

## File model — state lives in `.smartstack/ba/` (read first)

There is **no Studio, no SQLite, no backend route, no model router, no injected
`{{VAR}}` block, no `[ACTION]`/`[QUESTION]`, no `persist:` envelope, no
`--- CURRENT … ---` state, no sidecar/frontend, no i18n label codes**. State is
the `.smartstack/ba/` markdown tree in the user's project. You read it with
Glob + Read, and you write `.md` with Write/Edit. A skill that "persists" simply
writes a file; a skill that "reads current state" simply reads files.

The complexity flags in `_inventory.md` are now just a **note for the human** —
nothing routes a model on them. You expand whichever single `moderate`/`complex`
item the user points at.

## Inputs — read these from the tree (do NOT expect injected variables)

You are told **which one item** to expand — either by its code (e.g.
`UC-CRM-PIPELINE-OPPORTUNITES-002` or `BR-003`) or by "the next moderate/complex
item in `<scope>`". Resolve everything else by reading the tree:

1. **The scope's inventory** — `Glob .smartstack/ba/**/_inventory.md`, then Read
   the one for the scope in focus. It holds the shallow rows produced by Pass 1
   (code, title, kind, complexity flag, and for UCs a primary actor / for rules a
   type + linked UCs). This is your source for the item's **code** and **title**,
   which you must keep verbatim.
2. **The authoritative doc you will write into**:
   - a use case → the section's `use-case.md`
     (`.smartstack/ba/<APP>/<MODULE>/<section>/use-case.md`).
   - a business rule → the doc at the rule's declared scope, usually the module's
     `règles-métier.md` (`.smartstack/ba/<APP>/<MODULE>/règles-métier.md`),
     sometimes a section's. Read it to see which items already exist and to find
     the highest taken `BR-{NNN}`.
3. **Actors** — `.smartstack/ba/<APP>/acteur.md`. This is the ONLY source of
   valid `BA-…-AC-…` codes. Grep the `### BA-…-AC-…` headings for the available
   codes + labels before you reference any actor.
4. **Cross-references** — Grep the tree for sibling UCs (`use-case.md`) and rules
   (`règles-métier.md`) in the same scope so a `Règles liées` / `Cas d'usage
   liés` link points at a code that actually exists. If a referenced code is not
   found, it does not exist — do not invent it; offer to create it in its owner
   phase.

If the scope has no `_inventory.md`, this two-pass path was not started for it —
tell the user to run `/ba-modeling-inventory` first (or just use
`/ba-create-use-case` / `/ba-create-business-rules` directly), and stop.

## 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**: same positions as the definer skills (UC: after
   `**Postconditions**` ; BR: after `**Cas d'usage liés**`).
   **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 you expand — one item, fully detailed

### A use case (`UC-{APP}-{MOD}-{SEC}-NNN`)

Write the full Cockburn template into the section's `use-case.md`, matching the
`_workflow/doc-templates.md` skeleton verbatim (anchor + `### {CODE} — {title}`
heading; content in the user's language):

```markdown
### UC-CRM-PIPELINE-OPPORTUNITES-002 — Fusionner deux contacts en double
- **Acteur principal** : BA-001-AC-002 (Manager commercial)
- **Acteurs secondaires** : BA-001-AC-001 (Commercial)
- **Préconditions** : les deux contacts sont actifs ; l'utilisateur a le droit de fusion.
- **Flux principal** :
  1. Le manager ouvre la liste des contacts et sélectionne deux fiches.
  2. Le système présente un comparatif côte à côte ; le manager choisit la fiche survivante.
  3. Le système rattache les activités liées à la survivante.
  4. Le système marque le doublon comme supprimé et conserve une trace d'audit.
- **Flux alternatifs** :
  - ALT-1 : le manager annule avant confirmation → aucune modification.
- **Exceptions** :
  - EXC-1 : une activité a une contrainte de propriété exclusive → le système signale le conflit avant de réessayer.
- **Postconditions** : un seul contact reste actif ; la trace d'audit relie les deux sources.
```

Field discipline (same as `/ba-create-use-case`):

- `Acteur principal` and any `Acteurs secondaires` MUST be `BA-…-AC-…` codes
  copied verbatim from `acteur.md`. **Never** list the primary actor among the
  secondary actors. Never SCREAMING_SNAKE a label into a fake code.
- `Flux principal`: 5–10 single-action steps, present tense, explicit
  subject + verb. No UI-level steps ("clicks the Save button"). >12 steps means
  the UC is too coarse — flag it to the user rather than write a giant flow.
- Alternative flows branch from a valid main-flow step (`ALT-1`, `ALT-2`, …);
  exception/failure flows use the same shape (`EXC-1`, `EXC-2`, …).
- Keep `Acteurs secondaires`, `Flux alternatifs`, `Exceptions` present even
  when empty (`—`) so the file shape stays uniform. Do NOT write
  `Règles liées` / `Écrans liés` fields — they were dead data (written by no
  phase, read by no audit; removed 2026-08): the authoritative link lives on
  the rules side (`règles-métier.md` **Cas d'usage liés**) and the screens
  side (`screen.md` **Cas d'usage liés**).

### A business rule (`BR-{NNN}`)

Write the full rule into the authoritative `règles-métier.md` for the rule's
scope, matching the `_workflow/doc-templates.md` skeleton verbatim:

```markdown
### BR-007 — Fusion de contacts à forte valeur soumise à validation
- **Type** : workflow
- **Sévérité** : err
- **Portée** : CRM / PIPELINE / opportunites
- **Condition** : QUAND l'un des contacts source a un ARR > 10 000 € ALORS exiger l'aval d'un manager avant fusion.
- **Expression** : `ApprovalRequired = sources.Any(c => c.ArrTotal > 10000)`
- **Code d'erreur** : `pipeline.merge.approval`
- **Cas valides** : contact à 2 000 € d'ARR → fusion sans validation.
- **Cas invalides** : contact à 12 000 € d'ARR → fusion bloquée avec `pipeline.merge.approval`.
- **Cas d'usage liés** : UC-CRM-PIPELINE-OPPORTUNITES-002 (précondition)
```

Field discipline (same as `/ba-create-business-rules`):

- `Type` ∈ `validation | calculation | state-transition | ownership |
  constraint | derivation | workflow | integrity | cross-cutting | compliance |
  access` (domain-specific kinds accepted).
- `Sévérité` ∈ `err` (default) | `warn` | `info`.
- `Condition` is natural-language `QUAND … ALORS …` (FR) / `WHEN … THEN …`;
  reference fields by name, no passive voice.
- `Expression` is compact deterministic pseudo-code (SQL-/C#-like or math) — a
  hint a developer can implement without guessing.
- For an **enforceable** rule (it has a `Code d'erreur`), you MUST give at least
  one concrete `Cas valides` AND one `Cas invalides`, the invalid one naming the
  error. **Omit** `Code d'erreur` for pure filter/visibility rules; those may
  describe the observable absence instead of an error.
- `Cas d'usage liés` lists the `UC-…` codes (+ optional stage/step) the rule
  applies to; may be empty for pure invariants / policies.

## Codes — verbatim, never composed, never translated

- **Use case**: `UC-{APP}-{MOD}-{SEC}-NNN` — `{APP}`/`{MOD}` are the UPPERCASE
  application/module folder codes; `{SEC}` is the section folder code UPPERCASED
  with `-`→`_` (folder `exchange-history` → `EXCHANGE_HISTORY`). `NNN` is a
  3-digit counter scoped to the section.
- **Business rule**: `BR-{NNN}` — a 3-digit counter scoped to the
  `règles-métier.md` doc it lives in. The number, never the title, is the
  identity. Grep the doc's headings for the highest taken number.
- The item's code in `_inventory.md` is authoritative for **identity** — you are
  *refining*, not renaming. Copy the code and title verbatim. (If the inventory
  carries a legacy section-suffixed rule code like `BR-CRM-…-002`, write the rule
  under its scope's `règles-métier.md` using the canonical `BR-{NNN}` form for
  that doc and note the mapping in one line — the `BR-{NNN}` doc-local code is
  the form every audit and `create-prd` parse.)

## Writing — preserve every existing item (overwrite/append semantics)

The authoritative doc holds the whole scope's set of items. Two safe ways to
write the expanded item:

- **Edit** (preferred when the item already exists as a discovery-level stub):
  replace just that `### {CODE} …` block with the fully-detailed block, leaving
  every other item untouched.
- **Write** (when adding a brand-new detailed item): re-emit the **entire** doc —
  anchor + every existing item kept verbatim + your newly detailed item. A Write
  overwrites the file, so any item you omit is deleted. Re-list them all.

Never touch sibling items' content. Never convert the authoritative doc into a
rollup. If the doc is currently a placeholder (`_À définir…_`), replace it with
the real anchor + your one item.

## Self-check before writing (match the definer skills)

This skill is a **definer**, not an auditor — do **not** emit audit findings
(those are the `/ba-audit-use-cases` / `/ba-audit-rules` skills, which read the
tree and write their own verdict under `_audit/`). Before each write, verify:

**For a use case**
- Well-formed `UC-{APP}-{MOD}-{SEC}-NNN` code, kept verbatim from the inventory.
- Non-CRUD verb-object title (kept verbatim from the inventory).
- `Acteur principal` exists in `acteur.md`; primary actor not repeated in
  secondaries.
- ≥1 main-flow step, plus preconditions + postconditions present.

**For a business rule**
- Well-formed `BR-{NNN}` code, unique in the target doc.
- `Type`, `Sévérité`, `Portée`, `Condition`, `Expression` all present.
- If enforceable (`Code d'erreur` set): ≥1 valid AND ≥1 invalid example, the
  invalid one naming the error.
- Every referenced `UC-…` code is found in the tree by Grep.

Surface any gap to the user instead of writing a half-defined item. If the
expansion exposes a genuine open decision (e.g. "is the merge reversible within
24h?"), raise it in prose and let the user resolve it before you write — do not
silently pick.

## After writing

Acknowledge in **one line** the item you detailed (e.g. "`UC-CRM-PIPELINE-
OPPORTUNITES-002` détaillé — fusion de contacts."). If `_inventory.md` lists
more `moderate`/`complex` items not yet expanded, offer to continue with the
next one; otherwise hand back to the normal phase order
(`/ba-create-business-rules` after UCs, `/ba-create-rbac` after rules).

## Talking to the user

You speak like a business analyst, not like a tool. Don't surface skill names,
file paths, anchors, complexity flags, or the `.smartstack/ba/` layout at
runtime — talk about "this use case", "the rules for this section", "the merge
flow". Keep responses concise and focused on the single item and what comes next.

## Absolute prohibitions

1. **Never rename** — the inventory's `code` and `title` are the identity; you
   refine, you do not re-label.
2. **Never invent an actor, section, UC or rule code** — copy actor codes from
   `acteur.md`, section/module/app codes from folder names; Grep any reference
   and, if absent, defer to its owner phase.
3. **Never CRUD a UC title** (`Create`, `Edit`, `List`, `View`, …) — keep the
   business verb the inventory recorded.
4. **Never embed a business rule as a UC field** — the rule side owns the
   link (`règles-métier.md` **Cas d'usage liés** names the UC codes); rules
   are autonomous.
5. **Never include a UI step** ("clicks the Save button") in a flow — that's UI,
   not business.
6. **Never write a Level-2 rule without ≥1 valid AND ≥1 invalid example** when it
   is enforceable; keep it a draft until you can.
7. **Never resurrect a Studio mechanic** — no `[ACTION]`, no `[QUESTION]`, no
   `persist:`, no injected `--- CURRENT … ---`, no JSON envelope, no i18n codes,
   no sidecar. Read the tree, write the doc.