Use Case Design

Already-designed use cases

!find 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.)

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

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 number — a number is given when the case is designed, so skipping or dropping an entry leaves no gap.

   Nothing is saved before the answer.

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

   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
   only one option	don't ask — decide and record it in the spec

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

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

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 — 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 four kinds only — names belong to domain-modeling), 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.

Does not edit an approved spec (status: approved or implemented) — 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 (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.