git:20261013.cdd9a08 to git:20261013.9fb82ed

---

name: use-case-design

description: >

Delimits a use case's boundary and emits the parent spec that the layer skills

detail — trigger, payload, response, side effects, invariants, errors, and canonical

names. Use when the request involves "new use case", "design before implementing",

"implementation spec", a new endpoint/event/job, or when a request bundles several

actions and it's necessary to know whether it's one use case or several. First piece

of the `/new-feature` pipeline.

argument-hint: "[technical description of the use case]"

allowed-tools: Read, Write, Glob, Grep, AskUserQuestion, Bash(find:*), Bash(ls:*), Bash(grep:*), Bash(sort:*), Bash(tail:*)

model: opus

---

## Already-designed use cases

!`find "${CLAUDE_PROJECT_DIR:-.}/docs/use-cases" -mindepth 1 -maxdepth 1 -type d -name 'UC-*' 2>/dev/null | sort | tail -5`

Empty above → none yet, this will be `UC-001`. (`find`, not an `ls` glob: under zsh an unmatched glob

aborts the command before any fallback runs.)

## Target

$ARGUMENTS

---

# Use Case Design

Produces the use case's **parent spec**: the boundary, the flow, and the canonical

names every layer inherits. Writes no code. Weighs no storage technology: the storage family

and the search engine come from the request — stated, or inferred without ambiguity — or from one

factual question with no criteria and no recommendation; weighing them belongs to a planned

solution-design step (`@.claude/decisions/0147-document-storage-and-search-architect.md`). The

audit level is recorded only when the request asks for it, never proposed

(`@.claude/decisions/0149-auditing-variant-of-persistence-architect.md`). The

inbound protocol is the one technology asked with criteria, those of

`@.claude/rules/api-graphql.md` (`0146`).

**Entry rule: one use case, one side effect.** Before any question, apply the

boundary test from `references/scope-boundary.md`. A request with two side effects and

no shared transaction isn't one use case — it's two, and the right answer is to

propose the split, not design the hybrid.

**Vocabulary rule: technical input or nothing.** The request names the concrete

trigger (endpoint, topic, job, schedule) and the concrete destination (table, queue,

service). A request in business language — "when a user is created in the marketing

area" — doesn't get guessed at: stop and ask for a rewrite, listing the expected

vocabulary.

## How it's invoked

Two ways, and both matter: `/use-case-design` by hand, or chained by `/new-feature`

once that orchestrator exists. That's why it does **not** carry

`disable-model-invocation` — that field hides the skill from the model, and a skill the

model can't see is a skill the orchestrator can't call.

It's the first piece in the pipeline: it has no prior partial to require. The guard

against improper firing is the boundary test above — a vague request stops and asks

for a rewrite. Recorded in `@.claude/decisions/0007-pipeline-skills-invocation.md`.

## Why this isn't a subagent

It's a multi-step procedure whose heart is the interview with the user, and a

subagent doesn't see the conversation (axis 6 of the design interview). It writes

files in `docs/use-cases/**` — this repository's default for anything with a side

effect. The subagent lost by failing the counter-test's three questions; the full

record, with all four options and the notes, is in

`@.claude/decisions/0002-skill-use-case-design.md`.

Pinned to `opus`: the partial is what the executor implements verbatim. A pinned model does not make this a subagent — the interview needs the conversation, and the pin holding for the rest of the turn keeps `/new-feature` on the model that designed it (`@.claude/decisions/0081-skill-model-required-per-class.md`).

## Out of scope — and it's someone else's scope, not a lesser scope

| Doesn't decide | Why | Who decides |

|---|---|---|

| Kafka or SQS | The broker is an architecture choice, fixed earlier: the blueprint's `features` | The user, in `/init-project` |

| **Weighing** relational, document or search for a case — scenarios, trade-offs, pros and cons, a recommendation | A decision interview is a different job from recording a fact. This skill records the storage family and the search engine the request states, or asks one factual question when it does not (step 3, the `Storage` block); it never argues for one | A planned solution-design step, which will write the same `Storage` and `Search index` rows |

| Which design pattern to apply | A pattern shapes the classes of one layer, and this spec fixes no class | Each layer's partial, through `gof-design-patterns` § Design-time use |

| Writing classes, tests, or migrations | The spec describes what to create; creating is a different phase | The layer skills and, eventually, the executor agent |

| Per-layer detail (annotations, columns, exact HTTP status) | Each layer has its own rule and owner | The partial specs — see § Structure |

| **Path, verb, and HTTP status** | Fixing them here creates divergence: `api-rest.md` has URI and status rules this skill doesn't apply, and `30-rest.md` ends up correcting the parent spec's prose. Write the situation (`created`, `conflict with existing state`), not the number | `rest-api-architect`, in `30-rest.md` |

| **Idempotency mechanism** (`Idempotency-Key`, key table) | `api-rest.md` requires it on creation `POST`s; deciding "no" here was overwritten downstream and cost a second persistence pass. Record the business fact — "does repeating the request create a duplicate?" — and mark the technical decision as delegated | `rest-api-architect`, in `30-rest.md` |

| **Exception name and class** | A name fixed here gets demoted by `domain-modeling` (a subclass needs ≥ 2 call sites) and promoted back by a later case. Describe the situation (`email already in use`) and its kind (validation, not found, conflict, business rule) | `domain-modeling`, in `10-dominio.md` |

| **Shape of a domain field** — value object, `enum`, or plain primitive | The criterion is `@.claude/rules/value-objects.md`, which this skill does not read: a closed set with no formation rule to validate is an `enum` by criterion 3, and calling it a value object here guarantees a divergence on every such field. Name the component and its role; leave the shape open | `domain-modeling`, in `10-dominio.md` |

If the user asks for one of these, say which piece owns it and stop. Don't improvise

the decision.

## Procedure

1. **Validate the vocabulary.** Without a technical trigger and a technical

destination in the request, stop and ask for a rewrite, with the examples from

`references/scope-boundary.md`. Don't proceed by guessing.

2. **Count the side effects** using the boundary test. Two or more with no shared

transaction — or a request naming several operations (create, read, update, delete)

— is several use cases. **A split becomes backlog, not work:**

1. Present the list in dependency order (which UC stays synchronous, which reacts to

which event, which needs the aggregate another one creates) in **one**

`AskUserQuestion`, asking which one to design now.

2. Design only the chosen one.

3. Append the others to `docs/use-cases/BACKLOG.md`, from

`templates/backlog.md.example`: one line each, with the description ready to pass

to the next `/new-feature`. **Don't reserve a `UC` number** — that is given when the

case is designed, so skipping or dropping an entry leaves no gap in the sequence.

**Do assign a `BL-NN`**, the row's own identifier: highest existing plus one, counting

both tables of the file, never reused. It is what an impact row cites when the case

that satisfies a precondition is still in the backlog — without it the `Satisfied by`

column has nothing to name, and a real run invented `UC-004` twice to fill the sentence.

**Designing a case that came from the backlog:** its row moves from the table to

`## Retired`, with the `UC-NNN-<slug>` just assigned and the date. Not deleted — a spec that

cited that `BL-NN` is immutable once approved, so the citation has to stay resolvable exactly

when the case stops being backlog.

Nothing is saved before the answer.

3. **Interview** with `AskUserQuestion`, eight blocks, one per call when earlier

answers change the next questions:

| Block | Fixes |

|---|---|

| Trigger, payload, response | Who initiates, what data comes in, what goes out and in what shape. **For an HTTP trigger, also over which protocol** — REST, GraphQL, or both over the same input port — asked with the criteria of `@.claude/rules/api-graphql.md` § Choosing the inbound protocol, REST by default; the answer ends the `Trigger` row in its closed phrase (`inbound REST adapter` · `inbound GraphQL adapter` · `inbound REST and GraphQL adapters`), and a choice already written there by an earlier design step is kept, never re-asked. The protocol is per use case, not per project |

| Access — **always asked when the trigger is HTTP**, REST or GraphQL | Who may execute it: anyone, any authenticated caller, named roles or groups, only the owner of the resource — and whether someone (a support or admin role) may act on another's resource. The answer is the `Access` row; it is what decides whether `security-architect` runs |

| Side effects | Writes, external calls, publications — the boundary already counted in step 2, now confirmed |

| External calls — **always asked when a side effect reaches a system this service does not own** | Per system: what it is and what the case asks of it (read, or a write with an effect over there); its documentation link and whether it publishes an OpenAPI document; **how it authenticates this service** — as this service itself (an authorization server issues it a token), on behalf of the user who made the request, a static key, a username and password, a client certificate, a signature over each request, or none — and the credential's owner; whether it accepts an idempotency key on writes; what the business wants when it is down (fail now, or degrade to a named alternative); and, for a write, what happens when its result is unknown (stop, or reconcile later). The answers are the `External calls` row; a port of kind `external HTTP` in `10-dominio.md` is what then decides whether `http-client-architect` runs. Never asked as library, timeout or retry questions |

| Invariants and errors | Rules the domain guarantees, and the situation each violation produces — described, never named as an exception |

| Repetition, transaction, concurrency | Does repeating the request create a duplicate (business fact)? Where does the transaction open and close? What business key could collide? |

| Storage — **asked only when the request leaves it unclear** | Per aggregate the case writes or reads as its source: `relational` or `document (MongoDB)`; and whether the case searches that data through a search engine. **Recorded, not asked, when the request states it or it is inferred without ambiguity**: the request names the family or the engine ("store orders in MongoDB", "search the catalog in Elasticsearch"); the aggregate already lives in a table or a collection (step 4 reads it); the case extends data already persisted; the request names full-text search over named fields. **Never an inference**: a loose word — "document", "flexible", "fast", "scalable", "schemaless", "JSON". Unclear → one `AskUserQuestion`, a factual question with no criteria and no recommendation: *Will this data be persisted in SQL or NoSQL?* · `SQL (relational)` · `NoSQL (document, MongoDB)`. MongoDB is the only document engine in scope, so no engine question follows — it is recorded. The relational engine (Postgres, MySQL, Oracle) is never asked here: `persistence-architect` asks it. A search engine is asked only when the request names a search but no engine: *Which search engine holds the search index?* · `Elasticsearch` · `OpenSearch`. Whether the case wants a search index at all is never asked. The answers are the `Storage` and `Search index` rows, each with who chose |

| Audit — **recorded only when the request asks for it** | Per aggregate the case writes: `stamps` (when and by whom it was created and last changed) or `history` (every earlier version readable, with who and when). **Recorded from the request**: it asks who changed the data, when, what it was before, a trail, an audit, a history of changes. A REUSE aggregate keeps the level the code already has (step 4 reads it). **Never asked otherwise, and never proposed**: a case that says nothing about it records `none`. When the request asks for auditing without saying whether earlier values must be readable, one factual question: *Besides who changed it and when, must the earlier values be readable?* · `Who and when only` · `Who, when and the earlier values`. A document aggregate's `history` is recorded as asked — `persistence-architect` stops on it and says why. The answer is the `Audit` row, with who chose |

| Freshness — **always asked when the case returns data it did not just write** | How old may the answer be when it is served: must every read see the last write, or may it be some seconds or minutes old — in business words ("a balance may be up to 30 seconds old"). The answer is the `Freshness` row, `none` or a duration; a duration is what decides whether `cache-architect` runs. A case that only writes, or returns what it just wrote, records `none` without asking |

Don't move on with a block unanswered. A missing answer becomes a silent assumption

in the spec.

**Checklist before every `AskUserQuestion`.** Read each question and each option:

| Does it mention… | Then |

|---|---|

| an HTTP status code, a verb, or a path | don't ask — `rest-api-architect` decides |

| idempotency, `Idempotency-Key`, a key table | don't ask — ask the business fact instead |

| an exception class name | don't ask — `domain-modeling` decides |

| JWT, OAuth2, an API key, a filter, `@PreAuthorize`, 401 or 403 — for who calls **this** service | don't ask — ask who may execute it; `security-architect` decides the mechanism and the enforcement |

| a client library (`RestClient`, Feign, `WebClient`), a timeout, a retry count, a circuit breaker | don't ask — ask what the business tolerates when the other system is down or slow; `http-client-architect` decides. **Exception: how the other system authenticates this service is asked here, always** — it is a fact of the integration contract, and the credential's owner is a person to find before the design, not after |

| the shape of a domain field (value object, `enum`, primitive) | don't ask — ask what values the field admits; `domain-modeling` decides the shape |

| a cache, Redis, Caffeine, an expiry or TTL, a hit ratio | don't ask — ask how old the answer may be when served; `cache-architect` decides whether a cache exists and its shape |

| criteria, pros and cons, or a recommendation between SQL, a document store and a search engine — "which fits better", "faster", "more flexible" | don't ask — record what the request states, or ask the bare factual question of the `Storage` block; weighing them belongs to a solution-design step, not to this skill |

| tables, collections, indexes, a mapping, the relational engine | don't ask — `persistence-architect` and `search-architect` decide |

| auditing, a history or "who changed it" the request never mentioned; Envers, `_aud` tables, a revision, retention of the history | don't ask — `Audit` is recorded only from the request; the mechanism and the retention are `persistence-architect`'s |

| fewer than 2 real options | don't ask — decide and record it in the spec. The runtime rejects the whole batch over a single one-option question (`@CLAUDE.md` § Known pitfalls) |

A question whose answer another skill overwrites is worse than no question: it costs

the user's time and produces a divergence.

**Negative example** — never ask this:

> What does the endpoint return after creating? · `201 with body` · `201 without body` · `200 with id`

The user answered "201 without body"; `rest-api-architect` overwrote it by rule.

Ask this instead:

> After creating, does the caller need the created data back, or only a reference to it?

4. **Read the code before proposing.** `Glob`/`Grep` to know what already exists:

aggregate, ports, repository, controller. Every spec component carries a **NEW**,

**CHANGE**, or **REUSE** state. Proposing to create what already exists is this

skill's most expensive failure mode.

Read the approved specs too — every `UC-NNN-spec.md` whose `status:` is `approved`,

`implemented` or `implemented-blocked`. They are a **read-only contract**: reuse the

aggregate they already modeled, and never edit their files. A change this case needs in an approved case

goes into this spec's `## Impact on approved use cases` section — which case, what

changes, why. Decide what this case needs; don't defer or anticipate a decision for a

future case.

**An impact row that adds a precondition names which use case satisfies it.** This is the

one row shape that can break a case that was working: "reject when `status != ACTIVE`" is

correct, applies cleanly, compiles, passes — and leaves the earlier case reachable only

through a state nothing in the system produces. That happened: a use case became 422 on

every real call, the build stayed green, and the only trace was a comment in a test

fixture. So each such row carries a fourth column, **Satisfied by**, with one of:

- **an approved, implemented or implemented-blocked `UC-NNN`** — name it, and the

precondition is reachable today;

- **this very case** — it both adds the precondition and provides the transition;

- **a backlog row, by its `BL-NN`** — `docs/use-cases/BACKLOG.md` gives every row an

identifier for exactly this, and a `UC` number is **not** one of the answers here: a

backlog case has no `UC` number until it is designed, and writing one invents it. Name the

`BL-NN`, then this spec's `## Out of scope` repeats it and the consequence is stated

outright: from this change until that case ships, the earlier use case is unreachable end

to end. A reviewer may accept that; nobody can accept it without being told.

No fourth answer. "The tests construct the state" is not a satisfier — a fixture that

fabricates a state no production path can reach is the signature of this defect, not the

solution to it.

5. **Derive the real paths** from the active blueprint's `packages.map` — the same YAML in

a generated project, which carries its own copy. Never write a generic path when the

real one is knowable.

6. **Fix the canonical names** per `@.claude/rules/naming.md`: the use case and its

ports in the active blueprint's vocabulary (§ Architecture vocabulary — in this

repository, the naming comment in the blueprint's YAML), aggregate as a noun. Never

`<Verb><Noun>Service` by default: in a clean-architecture blueprint the use case is a

concrete `<Verb><Noun>UseCase` with no interface. No exception names — see § Out of

scope. These names are the inherited contract — the partial specs detail them, never

reinvent them.

7. **Fix the number and the slug.** This skill is their only owner — no caller passes

them in. `NNN` is the highest existing `UC-NNN` plus one, read from the injection at

the top (`UC-001` when there's none); the slug is kebab-case, from the trigger's verb

and noun.

8. **Generate** from `templates/use-case-spec.md.example` into

`docs/use-cases/UC-NNN-<slug>/00-caso-de-uso.md`. Create the folder; don't create the

empty partials.

**The template is the only source of the file's shape.** An existing

`00-caso-de-uso.md` is read in step 4 as a contract — aggregate, names — never as a

format exemplar: a spec written by an older version keeps lines the template has since

dropped, and copying one revives them.

The two diagrams are drawn last, from the text already written, per

`@.claude/rules/spec-diagrams.md`: the `sequenceDiagram` under `## Flow` from the numbered

list, and the `flowchart TD` under the **Out** table from the checks of the flow and the

table's situations. A name or an outcome a diagram needs and the text lacks goes into the

text first. Syntax and the renderer's traps: `references/mermaid-use-case-diagrams.md`; a

trigger, port or outcome the base template does not show (an event, a schedule, an

`external HTTP` port and its failures): `templates/use-case-diagram-variants.md.example`.

9. **Report and stop.** File path, the boundary applied, the backlog entries the split

produced (if any), and the table of who details each partial. **Don't invoke any

skill** — see § Handoff.

## Spec structure

One folder per use case. One file per owner — nobody edits another's file.

```

docs/use-cases/UC-001-create-user/

├── 00-caso-de-uso.md ← this skill. Boundary, flow, canonical names

├── 10-dominio.md ← domain-modeling

├── 20-persistencia.md ← persistence-architect

├── 30-rest.md ← rest-api-architect

├── 40-testes.md ← test-architect

└── UC-001-spec.md ← /new-feature: consolidated spec, carries `status:`

```

`docs/use-cases/BACKLOG.md` sits beside the folders: the use cases a split left for later.

While the partials don't exist yet, `00-caso-de-uso.md` stands on its own: the

component table already names every file to create and who details it. It's an

incomplete spec, not an invalid one. Which partials exist is read from the folder, never

written into this file: a status line here goes stale the moment the next partial lands.

## Handoff — declarative, never executable

This skill ends at the file. It doesn't call `rest-api-architect`, `gof-design-patterns`, or

`test-architect`, for two reasons: each one exclusively owns its own paths, and

merging design with execution makes "writes no code" impossible to verify.

The link lives in three passive places: the `Detailed by` column of the component

table, this section, and the final report — which prints the command the user runs

next, with the spec's path as the argument.

## Contract

**Class:** design — the territory is `skill_classes.design` in

`@.claude/schemas/extensions.json` and `ArchHook.java guard` enforces it. Writes inside the

use case folder and the backlog, nothing else; a write anywhere outside is refused with exit

2, not reported.

**Reads** `@.claude/rules/architecture-ddd.md` (Application section — where the

transaction opens, what doesn't go in the signatures), `@.claude/rules/naming.md`,

`@.claude/rules/error-handling.md` (the four kinds only — names belong to `domain-modeling`),

`@.claude/rules/api-graphql.md` (§ Choosing the inbound protocol only, for an HTTP trigger),

`@.claude/rules/spec-diagrams.md` (the sequence diagram and the flowchart) with

`references/mermaid-use-case-diagrams.md`,

the active blueprint's `packages.map` and naming convention, and this

skill's `references/scope-boundary.md` before counting effects.

**Writes** `docs/use-cases/UC-NNN-<slug>/00-caso-de-uso.md` and appends to

`docs/use-cases/BACKLOG.md`. Only those. The `10-` through `40-` partials belong to the

layer skills; the consolidated `UC-NNN-spec.md` belongs to the `/new-feature`

orchestrator.

**Owns** the use case number and slug. No other piece assigns them.

**Shares one sequence, with one other named writer.** `BL-NN` is assigned here when a split

appends a backlog row, and by `/new-feature`'s consolidation when a partial defers something to

the backlog. Those two, never a third: a design skill that appended its own row would compute

"highest plus one" against the same file in the same run and issue a duplicate.

**Does not** edit an approved spec (`status: approved`, `implemented` or

`implemented-blocked`) — reads it as a contract, and records the needed change in its own

impact section.

**Does not** write code, tests, migrations, or OpenAPI, and never writes under `src/`. Doesn't touch the inbound REST

adapter — the package the blueprint's `packages.map` gives that role

(`rest-api-architect`) —, the domain or application (`gof-design-patterns`,

`domain-modeling`), nor `.claude/rules/**`. Doesn't weigh a storage technology: records the

storage family and the search engine the request states or the user answers.

**Does not** reproduce rules. Cites by path; what the rule already says isn't repeated

in the spec.

**Also carries** `examples/` — twelve complete `00-caso-de-uso.md` fixtures for testing

`/new-feature` and `java-spring-boot-developer`, indexed in `examples/README.md`. Meta-repo

documentation, not this skill's runtime output: the `export` manifest keeps only

`SKILL.md`, `templates/` and `references/`, so this directory does not travel.