---
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.
