---
phase: useCases
kind: level
level: detail
---

# Phase 2 — DETAIL: flesh out each use case (Cockburn template)

> Scope: build the complete UML structure of every use case of the pinned
> section. The write protocol, UC code format and actors gate live in `SKILL.md`
> — this file is the Cockburn field guidance PLUS the cadence that governs how
> many UCs you draft before you stop.

## Goal

For each use case, fill the complete structure: preconditions, main flow,
alternative flows, exception flows, postconditions, plus the orthogonal metadata
(level, execution model, priority, secondary actors). **How many you do before
the user gets a say is the cadence** — pin it first (next section).

## When to enter this phase

- A section has discovery-level use cases in its `use-case.md` — titles with a
  `Flux principal` of `—` (which is NOT a flow), OR
- The user explicitly asks to "detail" / "flesh out" / "describe" a specific UC.

## Cadence — pin it ONCE, here, before drafting anything

Compute the worklist first: the UCs of the section whose `Flux principal` carries
no non-placeholder step. **An em dash `—` or `(aucun)` is NOT a step** — that is
exactly what the discovery pass writes, so a "is it empty?" test that counts the
dash finds nothing to do and details nothing. (Same predicate as the audit rules
UC-003 / BR-009 — `lib/ba-use-cases.undetailedUseCases`.)

<!-- detail-cadence:v1 — drift-tested against lib/detail-cadence.ts (edit ALL carriers or the suite fails) -->
| Cadence | What the model does | Where the human gate sits |
|---|---|---|
| **Pas à pas** | One item at a time: full draft, validation, write, next | One AskUserQuestion **per item** |
| **Par lot** | Draft every remaining item of the pinned scope internally, then present a compact recap + the open arbitrations | **One** AskUserQuestion for the whole batch, **one** write |
| **Enchaîné** | Draft and write the whole scope without stopping, then run the deterministic audit and publish its verdict + the arbitrations | None mid-run — the gate is the audit verdict + the arbitration list, after the fact |
<!-- /detail-cadence:v1 -->

**Default: `Par lot`.** Ask with ONE AskUserQuestion (the three cadences as
options, `Par lot` first), then hold it for the run.

Do NOT ask when:
- the worklist has **< 2 UCs** → behave as `Pas à pas`;
- the request already names it — "détaille tout" / "enchaîne" → `Enchaîné`,
  "un par un" / "je valide chaque" → `Pas à pas`, or an explicit `--cadence`;
- you are a **subagent** or in any context where AskUserQuestion is forbidden
  (a `/ba-loop` run) → `Enchaîné`, silently.

The user may switch mid-run ("repasse en pas à pas") — honour it from the next UC
on, never retroactively.

Three rules hold in EVERY cadence:

1. **ONE Write per batch.** `use-case.md` is overwritten whole — omitting a UC
   deletes it. Hold the drafts in memory and write the complete file once, at the
   end. Never N successive full-file rewrites.
2. **Never cross the pinned section.** Finishing the batch is not permission to
   start the next section.
3. **Publish your arbitrations.** Any UC where you had to invent a threshold, a
   trigger, a duration, or lean on an actor `acteur.md` does not list is named by
   its code, with the open question. In the batch cadences this is the only thing
   between "the user validated" and "the user rubber-stamped".

## Two ways to draft ONE use case (inside the cadence, not instead of it)

- **Full proposal (preferred, faster)** — draft the complete UC in prose. Default
  when the flow can be inferred from the title, actors and section context. This
  is the ONLY drafting manner available in `Par lot` and `Enchaîné`.
- **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). **Reachable only in `Pas à pas`** — it spends one
  turn per field, which is the opposite of what a batch was chosen for. Pick one
  manner per UC; never mix them.

In `Pas à pas`, on the user's answer to a UC:
- **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 (`Pas à pas` only)

Walk through each UC sequentially (1-3 turns typically). One turn per field is
the opposite of what a batch cadence was chosen for — in `Par lot` and
`Enchaîné`, draft the fields yourself and surface the open ones as arbitrations:

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 |

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 — per cadence

Whatever the cadence, a Write carries the **full set** of the section's UCs (the
newly detailed ones + the others re-listed verbatim — Write overwrites).

### `Pas à pas`

Write after each validated UC, then move to the next. Once ALL UCs of the section
are detailed, offer the next section — do not jump into it.

### `Par lot`

1. Draft every UC of the worklist. Nothing is written yet.
2. Present a **compact recap — one line per UC**:
   `UC-…-007 — Suivre l'entretien d'un véhicule — 6 étapes, 2 exceptions — 4 critères d'acceptation`
   The AC count belongs on that line: acceptance criteria are the test contract
   and a blocking audit rule, so hiding them at the single gate would empty the
   gate of its meaning.
3. Then the **arbitrations**, if any: one line per UC, the code and the open
   question.
4. Then ONE **AskUserQuestion**: `Tout valider` / `Reprendre certains UC` /
   `Repasser en pas à pas`.
   - *Tout valider* → step 5.
   - *Reprendre certains UC* → ask which ones (free prose / "Other"), re-draft
     **only those**, re-present **only those**, re-ask. Loop until validated.
   - *Repasser en pas à pas* → keep the drafts, switch cadence, resume at the
     first UC of the worklist.
5. **ONE Write** with the complete file. Acknowledge in one line, offer the next
   section.

### `Enchaîné`

Same drafting, no question, ONE Write. Then, mandatorily:

1. Run the deterministic audit for the dimension and publish its verdict:
   ```bash
   npx --prefer-offline tsx skills/business-analyse/audit-run/cli/audit-ba/index.ts \
     --spec '{"baRoot":".smartstack/ba","scope":{"app":"<APP>","module":"<MODULE>"},"dimensions":["use-cases"]}'
   ```
2. Publish the arbitration list.
3. The anti-extrapolation discipline applies verbatim: no UC without a verbatim
   trace in the tree (section context, actor, an existing code). Research never
   introduces a UC here.
4. **Stop at the section boundary.** Never chain onto the next section: an
   unattended run that also picks its own next scope is how a whole module gets
   authored without anyone looking.

## 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` — each rule references its
UCs there (`Cas d'usage liés`); the UC file carries NO back-reference field.
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.

## Refine an existing UC

A refine targets ONE named UC, so it runs `Pas à pas` whatever the cadence was
pinned for the pass — there is no batch to pace.

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.