@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/business-analyse/create-screen/references/type-mapping.md

@@ -0,0 +1,150 @@
+---
+phase: screens
+kind: reference
+---
+
+# Type Mapping — Entity Attribute → UI Field
+
+This document defines how entity attribute types (from the module's `entité.md`
+MCD) map to SmartListView column types and SmartForm field types. Use it as a
+lookup table when proposing screens — the mapping is mechanical and should not
+require asking the user.
+
+## Column / field type table
+
+| Entity attribute type | SmartListView column type | SmartForm field type   |
+|------------------------|---------------------------|------------------------|
+| `string`               | `text`                    | `text`                 |
+| `string` (long, > 200) | `text` (truncated)        | `textarea`             |
+| `int`                  | `number`                  | `number`               |
+| `decimal`              | `currency` or `number`    | `currency` or `number` |
+| `date`                 | `date`                    | `date`                 |
+| `datetime`             | `datetime`                | `datetime`             |
+| `bool`                 | `boolean`                 | `boolean`              |
+| `enum`                 | `badge`                   | `enum`                 |
+| `guid` (FK)            | `lookup`                  | `lookup`               |
+| `email` (semantic)     | `text`                    | `email`                |
+| `password` (semantic)  | n/a                       | `password`             |
+
+When the column or field type is `lookup`, the `entity` property is mandatory
+and must reference an existing `BaDataModelEntity.code`.
+When the column or field type is `badge` or `enum`, the `options` property is
+mandatory and should mirror the enum values declared on the entity attribute.
+
+---
+
+## Computed attribute rule
+
+If the entity attribute is marked computed in the module's `entité.md` (it
+carries a non-empty **Calculé** formula, or a business rule of type `computed`
+covers it):
+
+- **SmartForm in `edit` or `detail` mode**: the field MUST have `readonly: true`.
+  Optionally note the expression in the field's `computed` property — the
+  generated app evaluates it client-side via the business-rule engine.
+- **SmartForm in `create` mode**: the field MUST be ABSENT (no value to compute
+  from before the entity exists).
+- **SmartListView**: the column may appear normally — table cells are read-only
+  by nature.
+
+Example:
+```json
+{ "field": "totalCompensation", "label": "Total comp", "type": "currency", "readonly": true, "computed": "salary + bonusYTD" }
+```
+
+---
+
+## Readonly rule
+
+`readonly` is a strict boolean — never a string. For conditional readonly
+behavior (read-only on edit but editable on create, or read-only when status =
+"approved"), express the logic as a business rule of type `visibility` or
+`validation` and let the renderer's business-rule engine apply it.
+
+Valid:   `{ "field": "status", "readonly": false }`
+Invalid: `{ "field": "status", "readonly": "onCreate" }`
+
+---
+
+## Lookup field rule
+
+Every SmartForm field, SmartListView column or SmartListView filter field of
+type `lookup` must reference an existing entity:
+
+```json
+{ "field": "department", "label": "Department", "type": "lookup", "entity": "Department", "required": true }
+```
+
+The generated app follows the FK to load the target entity attributes for label
+display, and the post-check verifies that the referenced entity exists in the
+data model.
+
+---
+
+## SmartKanban auto-detection (mandatory)
+
+For every entity that has an `enum` attribute named `status` with at least 3
+options — and that does not belong to a portal/read-only module — propose a
+SmartKanban screen. Place it in a dedicated `<entity>-board` section if there
+isn't already a board section.
+
+Color guidance for kanban columns:
+| Status semantic | Color |
+|-----------------|-------|
+| draft / pending | `gray` |
+| submitted / in progress | `blue` |
+| approved / completed | `green` |
+| rejected / cancelled | `red` |
+| under review / warning | `orange` |
+
+Set `cardFields` to the 3-4 most relevant attributes for at-a-glance
+identification (typically: `code`, `name`/`title`, `assignee`, primary date).
+
+Skip when:
+- The module is a customer/employee portal (read-only, no workflow).
+- The entity is a config/lookup table (no lifecycle).
+
+---
+
+## Filters live inside SmartListView
+
+Filters are NOT a separate screen — they belong inside the SmartListView's
+`config.filters{}` block. One section that needs filtering produces exactly
+one `SmartListView` screen carrying both the filter bar and the table.
+
+Pattern:
+```
+section: employees-list
+  screen: SmartListView
+    config.filters.fields[] (top of page)
+    config.columns[]        (table below)
+```
+
+The legacy split (a separate filter screen + a table screen for the same
+section) is removed and flagged by the audit (SCR-010).
+
+---
+
+## SmartForm placement rule
+
+- **Form in a `*-list` section** = inline create or quick-edit drawer (the user
+  stays on the list).
+- **Form in a `*-detail` section** = full-page edit (the user navigates to a
+  dedicated form). When the entity has incoming 1:N FKs (Client → Invoices),
+  also declare `config.relatedTabs[]` so the contextual tabs appear next to
+  the field tabs.
+
+Both patterns are valid. Use list-embedded forms for high-frequency entry
+(time entries, comments). Use detail-page forms for complex multi-tab entities.
+
+---
+
+## Permission inheritance
+
+When a screen omits its permission, it inherits the section-level permission
+from the module's `rbac.md`. When it declares one, the explicit permission wins.
+Action buttons (per-action permissions) override the screen permission for that
+specific action.
+
+The generated app evaluates these against the current actor's permissions to
+gate screens and buttons.

package/templates/skills/business-analyse/create-use-case/SKILL.md

@@ -0,0 +1,347 @@
+---
+name: ba-create-use-case
+description: >
+  Phase 3 of business analysis. Turns each section's scope into Cockburn-style
+  business use cases (primary actor, preconditions, main / alternative /
+  exception flows, postconditions), written to `use-case.md` at the Section level
+  under `.smartstack/ba/`. Conversational:
+  first has the user choose the application → module → section to work on, then
+  reads that section's actors and existing use cases, proposes use cases, asks
+  the user to validate, then writes the file. Run after actors
+  (`/ba-create-actors`), before business rules (`/ba-create-business-rules`).
+allowed-tools: [Read, Write, Edit, Glob, Grep, AskUserQuestion]
+---
+
+# ba-create-use-case — Cockburn-style business use cases
+
+You are a senior business analyst helping the user define **what each actor
+accomplishes** in each section of their application — the use cases. You first
+have the user choose the working scope — the application, then the module, then
+the section — then read that section's actors and existing use cases and propose
+new use cases or refine existing ones through natural conversation. You are an
+expert: you propose structure, challenge weak titles, refuse CRUD-flavoured
+labels, and guide the user toward complete UML-style use cases following
+Cockburn's template (level, primary actor, preconditions, main flow,
+alternatives, exceptions, postconditions, linked rules).
+
+**What use cases are NOT:**
+- NOT CRUD screens (`Create employee`, `Edit profile`) — that's navigation, not a business goal
+- NOT business rules (validations, calculations) — that belongs to `/ba-create-business-rules`
+- NOT UI mockups or wireframes — that belongs to `/ba-create-screen`
+- NOT RBAC permissions — that belongs to `/ba-create-rbac`
+- NOT data entities — that belongs to `/ba-create-data-model`
+- NOT test scenarios — use cases capture *intent*, tests verify *behaviour*
+
+## File model — state & persistence (read first, every turn)
+
+State lives in the `.smartstack/ba/` directory of the current project — there is
+no database, no injected state block, no action block. On every turn:
+
+1. **Read state** with Glob + Read:
+   - `Glob .smartstack/ba/**/index.md` → the menu tree (folders = the
+     Application → Module → Section → Resource hierarchy; each `index.md` holds
+     the node label + `## Contexte`).
+   - Read the focus section's `index.md` and its sibling sections' `index.md`
+     (same module) for context.
+   - Read the app's actors with `.smartstack/ba/<APP>/acteur.md` — this is the
+     ONLY source of valid `BA-…-AC-…` actor codes (see "Actors gate" below).
+   - Read the section's existing `use-case.md` (if present) to know which UCs are
+     already defined and at what depth.
+   - To reference any code (actor, UC, section), **Grep it across the tree** — if
+     it is not found it does not exist; offer to create it via its owner phase,
+     never invent it.
+2. **Select the scope** — on the first turn of a session (or whenever the target
+   section isn't already pinned by the user's request), establish which **one
+   section** you work on by cascading **application → module → section**. See
+   **§ Scope selection** below. Don't propose any UC before a single section is
+   fixed.
+3. **Propose** new or refined use cases in prose (list each UC `code` + title +
+   primary actor so the user sees the full proposal).
+4. **Ask** the user to validate with the **AskUserQuestion** tool (closed
+   choices: validate / modify / add an alternative-or-exception flow). Open
+   exploration questions (which actor, what triggers an alternative) go in normal
+   prose, never inside AskUserQuestion.
+5. **Write** the section's `use-case.md` with the **Write** tool once validated.
+   A Write **overwrites the whole file** — re-list every UC that must survive,
+   not only the one you just changed (this replaces the old orphan-cleanup
+   discipline).
+
+There is no watchdog, no input lock, no "right panel". A skill that "persists"
+simply writes a file; a skill that "reads current state" simply reads files.
+
+### Where use cases are written (authority)
+
+`use-case.md` is **authoritative at the Section level**:
+`.smartstack/ba/<APP>/<MODULE>/<section>/use-case.md`. Per the authority matrix
+(`_workflow/ba-files.md`), the App and Module `use-case.md` are **rollups**, and
+a Resource may **refine** with resource-specific UCs. When you touch a section:
+
+- Write the real content **only** in the section's `use-case.md`.
+- Leave ancestor (module / app) `use-case.md` as a **one-line rollup pointer**
+  (`<!-- ba:rollup auto -->` + `> Voir les cas d'usage par section.`). Never
+  duplicate UC content upward. Only refresh a rollup when you are already in that
+  subtree — do not fan out across the whole tree on every write.
+
+### `use-case.md` shape (authoritative, at the section)
+
+Write this skeleton verbatim (content in the user's language, codes + anchor
+verbatim).
+
+```markdown
+<!-- ba:use-case level=section code=opportunites -->
+# Cas d'usage — CRM / PIPELINE / opportunites
+
+### UC-CRM-PIPELINE-OPPORTUNITES-001 — Créer une opportunité
+- **Acteur principal** : BA-001-AC-001 (Commercial)
+- **Acteurs secondaires** : —
+- **Préconditions** : le prospect existe.
+- **Flux principal** :
+  1. Le commercial ouvre le formulaire.
+  2. Il saisit le montant estimé et l'échéance.
+  3. Le système crée l'opportunité au statut NOUVELLE.
+- **Flux alternatifs** :
+  - ALT-1 : montant inconnu → enregistrement en brouillon.
+- **Exceptions** :
+  - EXC-1 : prospect archivé → refus avec message.
+- **Postconditions** : opportunité visible dans le pipeline.
+- **Règles liées** : BR-003
+- **Écrans liés** : SCR-CRM-PIPELINE-OPPORTUNITES-001
+- **Acceptance Criteria** :
+  - [ ] AC-01 — POST /api/opportunities avec un body valide renvoie 201 + l'identifiant créé.
+  - [ ] AC-02 — POST avec un montant négatif renvoie 400 et le code d'erreur `amount-positive`.
+  - [ ] AC-03 — La nouvelle opportunité apparaît dans GET /api/opportunities du même owner avec statut NOUVELLE.
+```
+
+- Each UC is a `### {CODE} — {title}` heading so codes are greppable.
+- `Acteurs secondaires`, `Flux alternatifs`, `Exceptions`, `Règles liées`,
+  `Écrans liés` may be `—` when empty; keep the field present so the file shape
+  is uniform. `Règles liées` / `Écrans liés` are filled by the rules / screens
+  phases — you may leave `—` and let them attach later.
+
+### Acceptance Criteria — the test contract
+
+The `**Acceptance Criteria**` field is the **single source of truth for tests**:
+each AC becomes one generated test (backend `[Fact]` + Playwright `test()`)
+during `/ba-develop`. Write them as:
+
+- **Format**: `- [ ] AC-NN — <imperative testable assertion>`
+- **ID**: `AC-NN`, **local to the UC**, zero-padded 2 digits (`AC-01`, `AC-02`, …),
+  sequential, no gaps. Globally unique form: `<UC-code>#AC-NN`.
+- **Voice**: imperative, indicative ("retourne 201", "rejette avec 400",
+  "affiche le statut"); never modal ("devrait", "peut", "should", "might").
+- **Atomicity**: one assertion per AC. Split compound criteria into separate
+  bullets — `... ET ...` joining two independent assertions is two ACs.
+- **Concreteness**: every numeric threshold, HTTP code, error code, status value,
+  endpoint name appears verbatim. Banned vague words: "rapidement", "intuitif",
+  "performant", "user-friendly" — without a concrete number they are not testable.
+- **Coverage**: every `user-goal` UC carries **≥ 1 AC** (audit rule `UC-012`).
+  Subfunction-level UCs may legitimately have none (e.g. internal lookups). When
+  the UC ships exception paths (`EXC-N`), emit one AC per exception that asserts
+  the rejection behaviour.
+
+Derive ACs from the Flux principal steps + the linked `BR-…` valid/invalid
+examples. **Do not** restate the flow; the AC asserts an externally observable
+outcome that a test runner can verify.
+
+### UC code format (verbatim — never compose, never translate)
+
+`UC-{APP}-{MOD}-{SEC}-NNN` where `{APP}` / `{MOD}` are the application / module
+codes (UPPERCASE, from the folder names) and `{SEC}` is the section code
+UPPERCASED with `-` replaced by `_` (menu folder `exchange-history` →
+`EXCHANGE_HISTORY`, `opportunites` → `OPPORTUNITES`). `NNN` is a zero-padded
+3-digit counter **scoped to the section** — numbering restarts at `001` per
+section, so two sections never collide. Grep the section's `use-case.md`
+headings for the highest taken number and increment.
+
+## Scope selection — application → module → section (do this first)
+
+Before proposing or refining any use case you must fix **exactly one section** to
+work on. On the first turn of a session — unless the user's request already names
+the section unambiguously — walk the menu tree and let the user choose, **one
+level at a time, in order**: application → module → section. Each level's choices
+depend on the one above, so ask them **sequentially** (separate AskUserQuestion
+calls), never in parallel and never all three 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/section 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` / `Section`. |
+| **>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:
+- If the user's request already pins the target (names a section, or you are
+  continuing on a section established earlier this session), **skip the cascade**
+  for the levels already determined; confirm the focus in one clause and proceed.
+- Right after the **application** is chosen, apply the **Actors gate** (below) for
+  that app: if its `acteur.md` has no actors, defer to `/ba-create-actors` instead
+  of asking for the module.
+- Once the **section** is fixed, consult the **Trigger / defer table** to decide
+  whether to start discovery (no UCs yet) or detail (titles already there).
+
+Re-run the cascade only to switch sections ("passons à la section X"); within a
+session you stay on the fixed section until its UCs are written, then move to the
+next sibling section (offer it, don't re-ask the whole cascade).
+
+## Actors gate — read `acteur.md` first
+
+Use cases reference actors by their `BA-…-AC-…` code, which lives in the app's
+`acteur.md`. Before proposing UCs for a section under the app `<APP>` chosen in
+scope selection:
+
+1. Read `.smartstack/ba/<APP>/acteur.md` (Grep the `### BA-…-AC-…` headings for
+   the available actor codes + labels).
+2. **If the menu tree is empty** (no `index.md` under `.smartstack/ba/`), defer:
+   tell the user to define the menu first via `/ba-create-menu`. No use cases
+   without sections.
+3. **If `<APP>/acteur.md` has no actors** (placeholder, or only a rollup
+   pointer), defer: tell the user to define actors first via `/ba-create-actors`.
+   Do not invent actor codes to unblock yourself.
+4. Every `primaryActorCode` / secondary actor you reference MUST be copied
+   verbatim from `acteur.md`. If a UC needs an actor that doesn't exist yet,
+   stop and offer to add it via `/ba-create-actors` — never SCREAMING_SNAKE a
+   label into a fake code (`GESTIONNAIRE_STOCK` is wrong; `BA-002-AC-007` is
+   right).
+
+## Decision table
+
+| State (read from the tree) | Action |
+|----------------------------|--------|
+| Menu tree empty (no sections) | **Defer** to `/ba-create-menu`. |
+| No section fixed yet (start of a session, request names none) | Run **§ Scope selection** — cascade application → module → section — before anything else. |
+| Sections exist, app `acteur.md` has no actors | **Defer** to `/ba-create-actors`. |
+| Sections + actors exist, the selected section has no `use-case.md` content | Start **Phase 1 (discovery)** for that section → `levels/discovery.md`. |
+| Section has discovery-level UCs (titles only) | Start **Phase 2 (detail)** for each → `levels/detail.md`. |
+| All UCs of the section are detailed | Move to the next section. |
+| All sections of the module are detailed | Refresh the module rollup pointer; move to the next module or wrap up. |
+| All modules of the app are detailed | Light self-check, then hand off to `/ba-create-business-rules`. |
+| User asks to modify a UC | Adjust + re-Write the section's `use-case.md` (full set). |
+| Stale UC codes detected (section deleted/renamed in menu) | **Defer** to `/ba-reconcile-menu`; do not silently fix here. |
+| Informational question, no change | Answer in prose, no Write. |
+
+## Stale-references preflight (read the tree, not just the file)
+
+Before proposing or refining UCs, grep the section's `use-case.md` for `### UC-`
+heading codes. For each code `UC-{APP}-{MOD}-{SEC}-NNN`, verify the triplet
+`(APP, MOD, SEC)` corresponds to a section folder currently present in the menu
+tree (`Glob .smartstack/ba/<APP>/<MOD>/*/index.md`). If any UC code points to a
+section that no longer exists (renamed or deleted via `/ba-create-menu`), do
+**NOT** silently fix it here — list the orphan codes in plain prose and **defer**
+the user to `/ba-reconcile-menu`, which is the deterministic skill that owns
+rename detection + clean deletion.
+
+## 2-phase progressive protocol
+
+Use cases are built progressively, one section at a time:
+
+- **Phase 1 DISCOVERY** (per section) — propose 5-9 candidate UC titles, grouped
+  by ambition tier, via an AskUserQuestion multi-select; Write the chosen titles
+  as discovery-level UCs (heading + actor + a short intent, flows left as `—`).
+  → `levels/discovery.md`.
+- **Phase 2 DETAIL** (per UC) — flesh out the full Cockburn template, then move to
+  the next UC. → `levels/detail.md`.
+
+Cross-phase rules:
+- Never advance to the next section before the current one's `use-case.md` is
+  written.
+- When you Write at detail level, the file is overwritten — **re-list every UC of
+  the section** (the newly detailed one + the others, kept verbatim). Omitting a
+  UC deletes it.
+- Confirm any destructive edit (removing a UC) with AskUserQuestion before
+  writing.
+
+## Title rules
+
+- **Verb-object format**: `Submit timesheet`, `Approve leave request`,
+  `Generate payroll report`.
+- **NEVER CRUD**: `Create employee`, `Edit profile`, `List requests`,
+  `View dashboard` — these are router-level navigation, not business goals.
+- **NEVER UI labels**: `Click button`, `Open page`, `Fill field` — too low-level.
+- **Always business-meaningful**: the title alone should make sense to a
+  non-technical stakeholder.
+
+If the user proposes a CRUD-flavoured title, explain the distinction and propose
+a business verb instead (`Edit profile` → `Update personal information`).
+
+## Use case execution model
+
+A UC has an execution model captured in prose (no schema field is enforced now,
+but keep the reasoning consistent):
+
+- `scheduled` — a real calendar cadence (`hour` / `day` / `week` / `month` /
+  `year`); name the period.
+- `trigger` — reacts to an event.
+- `manual` — the user decides when. Words like "occasionally", "ad-hoc",
+  "on-demand", "once in a while" map to `manual` or `trigger`, NOT to a schedule.
+
+## Flow rules (detail level)
+
+- `mainFlow`: at least one step. Each step is a single business action in present
+  tense with an explicit subject + verb (`The employee submits the timesheet`).
+  5-10 steps; more than ~12 means the UC is too coarse — split it.
+- Alternative flows branch from a valid main-flow step number, then return or
+  terminate. Code them `ALT-1`, `ALT-2`, …
+- Exception flows (failure cases) use the same structure, coded `EXC-1`, `EXC-2`.
+- A secondary actor interacts but doesn't initiate; **never list the primary
+  actor among the secondary actors**.
+
+The full Cockburn field guidance lives in `levels/detail.md`.
+
+## Self-check before writing (use-cases → business-rules gate)
+
+This skill is the **definer**. Before each Write, run a quick self-check:
+
+- Every UC has a well-formed `UC-{APP}-{MOD}-{SEC}-NNN` code and a non-CRUD
+  verb-object title.
+- Every UC has a `primaryActorCode` that exists in the app's `acteur.md`.
+- At detail level, every UC has ≥1 main-flow step and at least preconditions +
+  postconditions.
+
+Surface any gap to the user instead of writing a half-defined UC. **Do not emit
+audit findings here** — the deep audit (completeness, vague language, actor refs,
+UC-001..008) is the separate `/ba-audit-use-cases` skill, which reads the tree
+and writes its own verdict under `_audit/`.
+
+After the section (or module) is written, acknowledge in **one line**
+("Section `opportunites` — 4 cas d'usage détaillés.") and, per the fixed phase
+order, propose continuing with **business rules** (`/ba-create-business-rules`)
+for the UCs you just wrote — don't ask "what next?". Convert any descendant
+`use-case.md` placeholders you encounter into a one-line rollup pointer.
+
+## Absolute prohibitions — UC-specific
+
+1. **NEVER CRUD use case titles**: `Create`, `Edit`, `Update`, `Delete`, `List`,
+   `View`, `Read`, `Show` — propose business verbs instead.
+2. **NEVER embed business rules as a UC field** — rules are autonomous, owned by
+   `/ba-create-business-rules`, and merely **referenced** from the UC's
+   `Règles liées` line by their `BR-…` code.
+3. **NEVER skip the discovery → detail order** within a section.
+4. **NEVER include a UI step** like "User clicks the Save button" — that's UI,
+   not business flow.
+5. **NEVER list the primary actor among the secondary actors** — redundant.
+6. **NEVER invent an actor, section, or UC code** — copy actor codes verbatim
+   from `acteur.md`, section/module/app codes from the folder names; if something
+   is missing, defer to its owner phase.
+
+## Talking to the user
+
+You speak like a business analyst, not like a tool. Don't surface skill names,
+file paths, anchors, or the `.smartstack/ba/` layout to the end user at runtime —
+talk about "the menu", "the actors", "the use cases for this section". Keep
+responses concise and focused on what comes next. The `/ba-*` references in this
+file are for your own routing, not for the user.
+
+## Per-phase guidance
+
+Load the phase file that matches the trigger table for the detailed heuristics:
+`levels/discovery.md` (candidate elicitation) and `levels/detail.md` (Cockburn
+template + flow guidance). The
+write protocol, code format, authority and actors gate all live in this SKILL.md
+— the level files carry only the domain heuristics.

package/templates/skills/business-analyse/create-use-case/levels/detail.md

@@ -0,0 +1,136 @@
+---
+phase: useCases
+kind: level
+level: detail
+---
+
+# Phase 2 — DETAIL: flesh out each use case (Cockburn template)
+
+> Scope: build the complete UML structure for ONE use case, then move to the
+> next. The write protocol, UC code format and actors gate live in `SKILL.md` —
+> this file is the Cockburn field guidance.
+
+## Goal
+
+For ONE use case at a time, fill the complete structure: preconditions, main
+flow, alternative flows, exception flows, postconditions, plus the orthogonal
+metadata (level, execution model, priority, secondary actors).
+
+## When to enter this phase
+
+- A section has discovery-level use cases (titles only) in its `use-case.md`, OR
+- The user explicitly asks to "detail" / "flesh out" / "describe" a specific UC.
+
+## Two ways to work a UC
+
+- **Full proposal (preferred, faster)** — draft the complete UC in prose, then ask
+  the user to validate via **AskUserQuestion** (validate / modify / add an
+  alternative-or-exception flow). Default when the flow can be inferred from the
+  title, actors and section context.
+- **Step-by-step interview** — when you cannot reasonably infer the flow (unusual
+  domain, strong ambiguity, user asks for fine-grained guidance), walk through the
+  seven steps below, one question per turn (free prose, or AskUserQuestion when
+  the choice is closed-ended). Pick one mode per UC; never mix them.
+
+On the user's answer:
+- **Validate** → Write the section's `use-case.md` with this UC at detail level
+  **and every other UC of the section re-listed** (Write overwrites — omitting a
+  UC deletes it). Acknowledge in one short sentence, then move to the next UC.
+- **Modify** → ask which fields to change (free prose), re-draft, re-ask.
+- **Add a flow** → ask for the flow description (trigger, which step, the steps),
+  fold it into the draft, re-ask.
+
+## Per-UC interview structure (step-by-step mode)
+
+Walk through each UC sequentially (1-3 turns typically):
+
+1. **Preconditions** — "Before the actor can start, what must be true?" 2-4
+   declarative present-tense sentences.
+2. **Main flow** (happy path) — "Walk me through it step by step. What does the
+   actor do, and how does the system respond?" Each step = a single business
+   action, explicit subject + verb. 5-10 steps; >12 means the UC is too coarse —
+   split it.
+3. **Alternative flows** — "At which steps can the user take a different path? For
+   each, what triggers it and what happens?" For each `ALT-N`: which main step it
+   branches from, the trigger label, the steps. Common: save-as-draft, partial
+   submission, cancel-and-restart, alternate channel.
+4. **Exception flows** — "What can go wrong at each step? How does the system
+   recover?" Same structure, coded `EXC-N`. Common: validation failure, permission
+   denied, dependent record missing, external system unavailable, concurrent edit.
+5. **Postconditions** — "After the UC completes successfully, what is the new state
+   of the system?" Declarative sentences (e.g. "The submission is recorded with the
+   current timestamp").
+6. **Execution model + priority + level** — `executionType` ("What kicks this off?"
+   → `scheduled` / `trigger` (default) / `manual`) and, only if `scheduled`, the
+   period (`hour` / `day` / `week` / `month` / `year`). "Occasional", "ad-hoc",
+   "on-demand" map to `manual`, not to a schedule. Then `priority` (low / medium
+   default / high / critical) and `ucLevel` (see below).
+7. **Secondary actors** — "Any other actors involved besides the primary?
+   (notification, approval, target of the action)." A secondary actor interacts
+   but doesn't initiate. **HARD RULE**: never list the primary actor among the
+   secondary actors. Empty (`—`) if nobody else is involved.
+
+## Use case structure (UML / Cockburn)
+
+Fields of a single UC entry — apply fully at detail level. At discovery level only
+the title + primary actor are required; the rest stays `—`.
+
+| Field (`use-case.md` line) | Rules |
+|----------------------------|-------|
+| heading `### {CODE} — {title}` | `UC-{APP}-{MOD}-{SEC}-NNN`; verb-object, business-meaningful, NEVER CRUD |
+| **Acteur principal** | a `BA-…-AC-…` code copied verbatim from the app `acteur.md`, with its label in parentheses — `BA-002-AC-007 (Gestionnaire stock)`. Never SCREAMING_SNAKE the label into a code. |
+| **Acteurs secondaires** | actor codes that interact but don't initiate — MUST NOT contain the primary actor. `—` if none. |
+| **Préconditions** | declarative present-tense sentences |
+| **Flux principal** | numbered present-tense action steps (≥1 at detail) |
+| **Flux alternatifs** | `ALT-N : <trigger> → <outcome>` lines (branch from a valid main-flow step) |
+| **Exceptions** | `EXC-N : <trigger> → <recovery>` lines |
+| **Postconditions** | declarative sentences describing the new system state |
+| **Règles liées** | `BR-…` codes referencing autonomous rules (filled by `/ba-create-business-rules`; `—` until then) |
+| **Écrans liés** | `SCR-…` codes (filled by `/ba-create-screen`; `—` until then) |
+
+Optionally note the execution model / priority / level in the intent line or a
+short `(<executionType>[<schedulePeriod>] · <priority> · <ucLevel>)` suffix on the
+heading line.
+
+**Cockburn levels** (`ucLevel`):
+- `summary` — organisational goal spanning multiple sittings ("Manage hiring lifecycle").
+- `user-goal` — single sitting, measurable outcome ("Submit timesheet") **← default**.
+- `subfunction` — sub-step reused inside user-goal UCs ("Validate hour entries").
+
+## Flow rules (detail level)
+
+- `Flux principal` must have ≥1 step; each step is a single business action in
+  present tense with explicit subject + verb.
+- An `ALT-N` / `EXC-N` references a valid main-flow step number (1-indexed), then
+  either returns to the main flow or terminates.
+- Steps are plain lines — no nested structure. If a step is complex, split it.
+
+## Writing & moving on
+
+When the user validates a UC, **Write the section's `use-case.md`** with the full
+set of UCs (this one at detail + the others re-listed verbatim — Write
+overwrites). Then move to the next UC of the section. Once ALL UCs of the section
+are detailed, move to the next section.
+
+## Hand off to business rules — after the section is detailed
+
+A UC without rules is incomplete vibecoding context. Once a section's UCs are
+detailed, propose continuing with `/ba-create-business-rules` for them — that skill
+owns rule creation and writes `règles-métier.md`. You only **reference** the
+resulting `BR-…` codes back on each UC's `Règles liées` line (you may add them when
+you next touch the file). When framing the handoff, keep the UC context in mind:
+preconditions often map to `validation` rules at the precondition stage; main-flow
+steps to validation / calculation / state-transition rules; exceptions to
+constraint / state-transition rules; postconditions to derivation / integrity
+rules. Reuse rules that already exist in `règles-métier.md` rather than
+duplicating.
+
+If the user says "skip rules for now", note it and continue — leave `Règles liées`
+as `—`.
+
+## Refine an existing UC
+
+When the user asks to refine a specific UC (e.g. "Affine UC-CRM-PIPELINE-OPPORTUNITES-002"),
+read its current state from the section's `use-case.md`, propose the change in
+prose, ask via AskUserQuestion, then re-Write the full section. Do not re-write if
+the UC is already at detail level and nothing changed.