git:20260911.55588bd to git:20260916.d4ab12d

---

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, Bash, AskUserQuestion

---

## Already-designed use cases

!`ls -1d docs/use-cases/UC-* 2>/dev/null | tail -5 || echo "(none — this will be UC-001)"`

## Request

$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. Chooses no technology.

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

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

| Doesn't decide | Why | Who decides |

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

| REST or GraphQL, SQL or NoSQL, Kafka or SQS | Technology is an architecture choice, fixed earlier: the blueprint's `packages.map` and `features` | The user, in `/init-project` |

| Which design pattern to apply | A pattern is born from a symptom in the code, not from a spec | `java-patterns` |

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

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

3. **Interview** with `AskUserQuestion`, four 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 |

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

| Invariants and errors | Rules the domain guarantees, and the `@.claude/rules/error-handling.md` exception born from each violation |

| Idempotency, transaction, concurrency | Safe to re-run? Where does the transaction open and close? What key could collide? |

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

in the spec.

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.

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

generated project, from the packages documented in the root `CLAUDE.md` and the

module `CLAUDE.md` files. Never write a generic path when the real one is knowable.

6. **Fix the canonical names** per `@.claude/rules/naming.md`: inbound port

`<Verb><Noun>UseCase`, implementation `<Verb><Noun>Service`, aggregate as a noun,

exceptions from the `@.claude/rules/error-handling.md` family. These names are the

inherited contract — the partial specs detail them, never reinvent them.

empty partials.

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

```

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 — and the header says so.

## Handoff — declarative, never executable

This skill ends at the file. It doesn't call `rest-api-architect`, `java-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

**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 active blueprint's `packages.map`, and this

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

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

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

`domain-modeling`), nor `.claude/rules/**`. Doesn't decide technology.

**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: step 6.7 of `project-bootstrap` does not

copy this directory into a generated project.