# Use case conventions

Canonical reference for how the project stores use cases and what metadata they carry.
The full writing method is in [`../use-case-guide.md`](../use-case-guide.md)
(Cockburn, *Writing Effective Use Cases*). This file is about machine conventions.

## Identifiers

| Format | Purpose | Example |
|---|---|---|
| `us-NNNN` | Summary UC and free top-level user goal | `us-0002` |
| `us-NNNN.NN` | User goal inside a summary decomposition | `us-0002.01` |
| `us-NNNN.NN.NN` | Subfunction, if extracted into its own file | `us-0002.01.03` |

- Numbering runs through the whole registry, with leading zeros (4 digits at the top level).
- IDs do not change during a UC's life. When you delete a UC, **do not reuse** the number.
- Directory name: `us-NNNN-<kebab-name>/`. Child file name: `us-NNNN.NN-<kebab-name>.md`.

### Naming files and folders (`kebab-name`)

Every UC lives in a folder whose name ends with a short `kebab-name`. This name is **not a transliteration of the title**. It is a short label for the UC's *goal*.

**Rule.** `kebab-name` = **1 to 3 words on Simple English**, joined by `-`, lower case, ASCII letters / digits / `-` only.

**Algorithm.**

1. State the goal in one short sentence: "the actor wants to ...". Use the *goal* behind the title, not the title text itself.
2. Pick the 1 to 3 most common English words that name this goal. Prefer verbs in the base form.
3. Join them with `-`. Allowed characters: `[a-z0-9-]`.
4. Drop stop words (`a`, `the`, `of`, `in`, `for`, `to`, `with`, `new`).
5. Keep proper nouns and short technical terms as-is: `ts`, `api`, `json`, `sql`, `csv`, `email`, `pdf`.

**Examples (Russian title → `kebab-name`):**

| Title | ❌ Bad | ✅ Good | Why |
|---|---|---|---|
| Обзор архитектуры типов в TypeScript | `obzor-arhitektury-tipov`, `review-typescript-types-architecture` | `represent-ts-architecture` | Goal: "show how TS represents types as architecture". `ts` is a proper noun, kept as-is. |
| Зарегистрировать нового пользователя | `zaregistrirovat-novogo-polzovatelya`, `register-new-user` | `register-user` | "new" is implicit; `register` + `user` is enough. |
| Получить отчёт о продажах | `poluchit-otchyot-o-prodazhakh` | `get-sales-report` | "о продажах" → `sales`; object = `sales-report`. |
| Управление правами доступа | `upravlenie-pravami-dostupa` | `manage-permissions` | Abstract sea-level goal: `manage`, not CRUD. |
| Импортировать заказы из CSV | `importirovat-zakazy-iz-csv` | `import-csv-orders` | "из CSV" is the source, not the verb's object. |
| Отправить email подтверждение | `otpravit-email-podtverzhdenie` | `send-confirmation-email` | 3 short words; `email` keeps the medium. |

**Anti-patterns.**

- Transliteration of the title. The `kebab-name` is a goal label, not a translation.
- More than 3 words. If you need more, the goal is fuzzy — reformulate the UC.
- Articles, prepositions, or conjunctions inside the name.
- CamelCase, snake_case, or non-ASCII letters.
- Re-using the title verbatim in English (e.g. `represent-the-architecture-of-types-in-typescript`).

See the procedure step in `../SKILL.md` (procedure B step 2 and the matching step in C1 / C2).

## Goal levels (Cockburn)

| `level` (frontmatter) | Meaning | When |
|---|---|---|
| `summary` | Strategic "umbrella" goal; decomposes into user goals | Covers several user goals |
| `user-goal` | One task the actor finishes in one go ⭐ primary level | "Can the actor walk away happy after one session?" — yes |
| `subfunction` | Helper step "under water" | Repeats across several UCs or clutters the main flow |

## Scope

| `scope` (frontmatter) | What the black box holds |
|---|---|
| `enterprise` | The whole organization, business processes |
| `system` | The system you build, end to end |
| `subsystem` | One module or service |

## Directory layout

```
{{USECASES_DIR}}/                       ← usually docs/usecases/ (configurable)
  registry.md                           ← single registry
  usecase-map.puml                      ← top-level map
  registry/
    us-0001-<kebab-name>/
      usecase.md                        ← summary UC
      usecase-map.puml                  ← decomposition map (this UC + children)
      children/
        us-0001.01-<kebab-name>.md      ← user goal
        us-0001.02-<kebab-name>.md
    us-NNNN-<kebab-name>/               ← free top-level user goal
      usecase.md                        ← no children/, no decomposition map
```

- A summary UC **always** has `children/` and its own `usecase-map.puml`.
- A free top-level user goal lives in a `us-NNNN-.../` directory with only `usecase.md`,
  no `children/`, no decomposition map of its own.
- A subfunction either lives as `children/us-NNNN.NN.NN-...md` or directly inside the parent's body.

## Frontmatter fields

Common to all levels:

| Field | Type | Purpose |
|---|---|---|
| `id` | string | UC identifier (see above) |
| `title` | string | Actor's goal in active form: "Verb + object" |
| `level` | enum | `summary` \| `user-goal` \| `subfunction` |
| `scope` | enum | `enterprise` \| `system` \| `subsystem` |
| `primary_actor` | string | Whose goal this serves (several allowed, comma-separated) |
| `secondary_actors` | list | Other actors (may be `[]`) |
| `status` | enum | `draft` \| `backlog` \| `in-progress` \| `done` \| `deprecated` |
| `version` | string | SemVer of the UC document (not the code!) |
| `created` / `updated` | date | `YYYY-MM-DD` |
| `format` | enum | `brief` \| `casual` \| `fully-dressed` |
| `methodology` | string | `use-case-guide.md (Cockburn)` |
| `language` | string | `ru` (default for this project) |

Links:

| Field | Type | Purpose |
|---|---|---|
| `parent` | string | For user-goal or subfunction: parent UC ID |
| `children` | list | For summary only: user-goal IDs in the decomposition |
| `related_change` | string \| null | OpenSpec change ID (`openspec/changes/<id>/`) |
| `related_specs` | list | OpenSpec capability IDs (`specs/<id>/spec.md`) |
| `related_design` | string \| null | Path to the change's design.md |

For `registry.md` we use: `id` (`us-registry`), `type: registry`, `version`,
`created`, `updated`, `related_directory`, `related_map`, `methodology`, `language`.

## Format levels

| format | Contents | When |
|---|---|---|
| `brief` | One paragraph of the essence | Early stage, backlog |
| `casual` | Several paragraphs: main path + main deviations | Most UCs |
| `fully-dressed` | All fields + steps + extensions + variations | Critical or complex UCs |

Keep most UCs in brief or casual. Fully-dress only the important ones.

## PlantUML maps

Two kinds of maps, both named `usecase-map.puml`:

### Top level (`{{USECASES_DIR}}/usecase-map.puml`)

Shows:
- every UC at `summary` level;
- UCs at `user-goal` level **only if** they are not part of the decomposition
  of any shown summary.

It does not show user goals from `children/`. That would duplicate the decomposition maps.
Source of truth: `registry.md`.

### Decomposition (`registry/us-NNNN-.../usecase-map.puml`)

Shows:
- user goals (`children/`) inside `package "us-NNNN" { ... }`;
- the parent summary is **not** drawn as a usecase — it is shown only by its ID
  in the package header;
- primary actor → UC arrows; optionally `<<precedes>>` between user goals when the order is strict.

### Stereotypes and arrows

| Stereotype | Actor→UC link |
|---|---|
| `<<summary>>` | primary: `actor --> UC` |
| `<<user goal>>` | primary: `actor --> UC`; secondary: `actor ..> UC : secondary` |
| `<<subfunction>>` | primary: `actor --> UC` |

The visual style of the maps (ELK layout, Solarized palette, `skinparam`,
no `note`, package rules, stereotype placement) lives in the dedicated skill
**usecase-map-puml** — the authoritative source for styling. Do not duplicate the style here.

## Link with OpenSpec

A UC points to its implementation through frontmatter, not by copying text:

- `related_change` → `openspec/changes/<id>/` (the change that implements the UC);
- `related_specs` → capabilities (`specs/<id>/spec.md`) covered by the UC;
- `related_design` → `openspec/changes/<id>/design.md`.

If the UC is not linked to a change yet, leave `null` / `[]`. Fill them in as the UC moves
into implementation.

## Choosing the use cases directory

`{{USECASES_DIR}}` defaults to `docs/usecases/`. Configure it with the `USECASES_DIR`
variable or ask the user on first set up. All relative links in the templates count from
this directory.