# kinds/use-case.md — one use case, after the fact

The playbook `/ba-change` loads for `kind: use-case`. The frame (scope, the
impact CLI, the Write discipline, verify, the impact walk, audits, hand-off)
is in `SKILL.md`; this file carries what is specific to a **use case**: the
questions that analyse the request, the ones that challenge it, the grammar to
author, and what its downstream looks like.

Owner document: `<APP>/<MODULE>/<section>/use-case.md` (full re-Write).
Grammar: `_workflow/doc-templates.md` § use-case.md; Cockburn field guidance
in `ba-create-use-case/levels/detail.md`. Code: `allocation.next`, verbatim.

## 1. Analyse the request

One grouped AskUserQuestion (max 4 questions), phrased in business terms:

| Question | Why it matters |
|---|---|
| **Who** performs it — the primary actor (from `acteur.md`, shown by label), the secondary actors? | UC-008; a new role is `/ba-change` kind=actor FIRST |
| **What goal** does the actor reach — one sentence, the title (« Relancer un prospect ») ? | the duplicate check runs on it; the level is decided from it |
| **Where** — which section of the module? What triggers it, what must be true before (preconditions), what is observable after (postconditions)? | the section decides the code family; pre/postconditions become AC material |
| **What can go wrong** — the alternative and exception paths (« prospect archivé », « montant manquant ») ? | one AC per EXC-N (UC-022); a UC with no failure path is rarely real |

Also settle: is it **scheduled** (a job, no actor — `scheduled` in the flow)?
Does it **read only** (a consultation UC still needs a surface)?

## 2. Challenge it

Read `report.existing`, `report.impact` and ask yourself — then the user —
before writing anything:

- **Is it a use case at all?** A step somebody forgot inside an existing UC,
  an alternative path, an exception → it is a **modification** of that UC
  (op=modify with its code), not a new one. A « le système doit… » sentence
  with no actor goal → probably a **business rule**.
- **Is it a user goal or a subfunction?** A subfunction (« sélectionner un
  client ») is reached through its callers' surfaces and is exempt from the
  surface rule; declare the level honestly — an undeclared level is a
  user-goal, and an uncovered user-goal is an err (SCR-024).
- **Does it already exist?** `existing.exact[]` → reuse / modify;
  `existing.similar[]` → ask whether the new one is really distinct;
  `existing.crossApp[]` → tell the user it exists elsewhere, never write there.
- **Does it belong here?** The section is the scope of the goal. A goal that
  spans two sections is two UCs, or one UC at the section that owns the
  aggregate root.
- **Does it introduce a new state?** (« l'opportunité passe en RELANCÉE ») →
  the status enum, a state-transition rule and a screen must follow — say it
  now (kinds attribute + business-rule + screen, in that order).
- **Does it need a new right?** (« seul le manager peut… ») → an RBAC row
  (`/ba-change` kind=permission after the UC), maybe a segregation-of-duties
  check.
- **What proves it works?** Every AC is a single testable assertion
  (`POST … renvoie 201`, `… renvoie 409 et le code …`); one per exception
  path at least; no AC = no [Fact] downstream (DEV-TEST-001/008).

Requalify when needed and say why in one line. Only then author.

## 3. Author

Write the block with the owning grammar (doc-templates § use-case.md):

```markdown
### <allocation.next> — <Title> (user-goal)
- **Acteur principal** : BA-001-AC-001 (Commercial)
- **Acteurs secondaires** : —
- **Préconditions** : …
- **Flux principal** :
  1. …
- **Flux alternatifs** :
  - ALT-1 : … → …
- **Exceptions** :
  - EXC-1 : … → …
- **Postconditions** : …
- **Sources** : SRC-NNN §n            (when the registry exists)
- **Acceptance Criteria** :
  - [ ] AC-01 — …
  - [ ] AC-02 — EXC-1 : … renvoie 4xx et le code `…`.
```

- Actor codes **verbatim** from `acteur.md`, label in parentheses.
- Level in the heading parenthetical (`user-goal` | `subfunction` | `summary`).
- ACs `AC-NN`, zero-padded, sequential from 01, one per line, em-dash separator.
- Then the full re-Write of the section doc (SKILL.md Step 3) and the verify
  (`expectCode` = the new code, `baselineCount` = `existing.count`).

## 4. Verify

`report.verify.ok` true: found, delta +1, `lost[]` empty, no duplicate,
sources cited when required. A `lost` entry names a malformed AC bullet or a
near-miss heading — fix it (a full re-Write is the right moment to repair a
pre-existing near-miss), verify again.

## 5. Propagate — what a new use case drags along

The CLI's `impact[]` is the list; this is what each step means for a UC:

1. **Rules** (`ba-create-business-rules` § Single-UC entry point) — each
   precondition → a `validation` rule; each computation → `calculation`; each
   state change → `state-transition`; each exception trigger → `constraint`;
   link the existing ones (`Cas d'usage liés` += the code) instead of
   duplicating. BR-007 errs on a UC with no rule.
2. **RBAC** — the actor must hold ≥ 1 row; a new business action (approve,
   export, relaunch…) needs its own row at the section grain → `/ba-change`
   kind=permission. XD-004 / RBAC-004.
3. **A surface** — the screen of the section that serves the goal: add the
   code to its `- **Cas d'usage liés**`, or an action line tagged
   `UC: <code>` for an instance/collection verb (`ba-create-screen` § Custom
   actions), or a new screen (`/ba-change` kind=screen). SCR-024 errs on a
   user-goal UC with no surface. `data.candidates` lists the screens of the
   section with their pagespec.
4. **Data model** — every entity / attribute the flow names must exist in
   `entité.md`; a missing one is `/ba-change` kind=attribute (the UC is its
   trace), followed by the MANDATORY `derive-lookup-grants --mode derive`.
5. **Pagespec delta** — the pagespec of each screen touched (joined on its
   `screenCode`): `linkedUseCases[]` += the code; a custom action → an
   `actions[]` entry with `ucReference`; a `kind: api` action → its handler
   bullet in `prd.api.md`. Json block only. PRD-131 / PRD-097.
6. **derive-rule-links backfill**, then **derive-uc-coverage** — the code
   must come back `covered` on both legs. Proof, not prose.
7. **Lifecycle check** when a workflow / state-transition rule was authored.

## 6. Audit

`audit-ba` on the module, dimensions `use-cases, rules, rbac, screens,
cross-dimension`, plus `/ba-audit-prd` when pagespecs exist. What an err
means here: UC-008 (actor unknown), UC-012 (no AC), UC-022 (an exception
without its AC), BR-007 (no rule), XD-004 (actor without permission), SCR-024
/ PRD-131 (no surface / not in the pagespecs), PRD-097 (a `ucReference` that
does not resolve).

## Modify variant (op=modify)

The same walk without allocation, plus:

- **Never renumber an AC.** A renumbered or removed `AC-NN` leaves a stale
  `[Trait("AC","<UC>#AC-NN")]` behind — a green test on a deleted assertion
  (DEV-TEST-003 err). New ACs go at the END; an obsolete assertion is
  reworded, not deleted, unless the user decides the behaviour is gone (then
  the test is deleted with it in Phase 4).
- A **changed actor** re-opens step 2 (XD-004).
- An **added exception flow** needs its AC (UC-022) and usually a rule.
- A **changed goal** re-opens the surface question: the screen's `Cas
  d'usage liés` and the pagespec `linkedUseCases[]` still name the right code,
  but the action that served the old goal may no longer fit.
- Verify expects delta **0**.