new-use-case

name: new-use-case description: Define a new use case by interviewing the user, then write a filled-in `spec/use-cases/use-case-NNN-short-name.md`. Use when the user wants to add, draft, or specify a new feature/use case.

New Use Case

Interview the user to capture a new use case, then write it to spec/use-cases/use-case-NNN-short-name.md using spec/use-cases/use-case-template.md as the structure.

The goal is a complete, implementation-ready spec. A use case that lacks actors, preconditions, a trigger, a main flow, alternative flows, postconditions, business rules, or routes is not done — keep interviewing until every section is filled in.

Before You Ask Anything

Read spec/project-context.md and spec/architecture.md so questions stay consistent with the project's vision, users, and stack.
Read spec/datamodel/datamodel.md if it exists — refer to actual entities when discussing data.
List spec/use-cases/ to:
- See existing use cases (don't duplicate them; suggest references where flows overlap).
- Determine the next free NNN number (zero-padded, e.g. 004).
Read spec/use-cases/use-case-template.md — it is the authoritative shape of the output.

If any of these files are missing, tell the user and stop; the project isn't ready for a use case yet.

Interview

Drive a focused conversation. Ask one topic at a time, in the order below. Keep questions short. When there is a clear small set of choices (primary actor, access level, UI tech, status), present them as a multiple-choice question. Use plain chat for open-ended answers (main flow, alternative flows, business rules). Never ask the user to "fill in the template" themselves — you are doing that for them.

After each answer, restate your understanding in one sentence before moving on, so misunderstandings surface early.

1. Goal sentence (capability and value)

What capability is this use case about? Who is the actor? What value do they get?
Produce the As a … I want to … so that … sentence and confirm it. This becomes the Goal: line in the template.

2. Short name (derive silently)

Derive a kebab-case short name (2–4 words) from the goal sentence. Use it as the filename suffix. Do not ask the user — just pick a sensible one (e.g. "browse movies" → browse-movies, "user buys ticket" → buy-ticket). It will show up in the final summary; the user can correct it there if they care.

3. Actors

Confirm the primary actor (the role that initiates the use case). The goal sentence usually names it — read it back.
Ask whether there are any secondary actors (external systems or other roles the use case interacts with — payment gateway, email service, second role). If none, omit the line.

4. Preconditions

What must already be true for this use case to start? Authentication, prior use cases having run, data that must exist.
If the user genuinely has none, write "None".

5. Trigger

What event starts the use case? A click, a route navigation, a scheduled job, an external event.
Often inferable from the main flow's first step — propose and confirm.

6. Main flow (happy path, numbered)

Ask the user to walk through what happens, step by step.
Write the steps as numbered actor/system pairs that alternate (1. User clicks X. 2. System shows Y. 3. User submits Z. 4. System persists and navigates to W.). Each step is one observable action.
If the user is vague, ask targeted follow-ups: entry point, what they see, what they click/type, what the system does, when the flow ends.
Keep steps atomic — alternative flows will branch off specific step numbers, so coarse steps are hard to extend later.

7. Alternative flows

Walk each main-flow step and ask: "what can go wrong at this step?" Look for: validation failures, permission denials, empty states, external-system errors, conflicts.
For each alt flow, capture: short name, the step it branches from, the condition that triggers it, the mini-flow, and whether it returns to the main flow or ends the use case.
If the user genuinely has nothing for a step, accept that and move on. Do not invent failures. But ask for every step.

8. Postconditions

On success: what is true after the main flow completes? (E.g. "Order is persisted with status PENDING", "Email is sent".)
On failure: what is true if any alternative flow ends the use case? (E.g. "No order is created; cart is unchanged".)

9. Business rules

Ask what rules constrain the flow beyond what's already in the flows: required fields, limits, visibility/access, validation, edge cases, time/ordering rules.
Encourage at least two or three. Each rule should be testable. Reference the data model and existing use cases when relevant.

10. UI / routes

Ask whether this is a public (React/Hilla) or admin (Vaadin Flow) view — this drives routing, access annotations, and test style. Ask this as a multiple-choice question.
Capture the route path(s), access level (public / authenticated / ADMIN), and any layout requirements (component types, key interactions, responsive needs).
If the user has a mockup or image, ask them to point at it and reference it in the file.

11. Tests (placeholder)

Suggest a test class name based on the short name (e.g. BrowseMoviesTest, BuyTickets.test.tsx).
List planned coverage as bullets: Main Flow steps, each Alternative Flow, each Business Rule. The actual tests are written later by /use-case-tests; here we are just declaring intent.

Draft and Confirm

Once all sections are gathered:

Show the user a compact summary of every section: goal, actors, preconditions, trigger, main flow (numbered), alt flows, postconditions, business rules, route table, planned tests. Do not show the full markdown yet — keep the review skimmable.
Ask for any corrections or additions.
Only after the user approves, write the file.

Writing the File

Path: spec/use-cases/use-case-<NNN>-<short-name>.md, where <NNN> is the next free number from step 3 of "Before You Ask Anything".
Start from spec/use-cases/use-case-template.md — keep the same section order, headings, and tables. Remove the leading > Copy this template … instruction block.
Fill every [bracketed placeholder]. Do not leave any behind. If something is genuinely unknown, ask the user before writing — don't invent.
Set **Status:** Pending and **Date:** <today's date>.
Use - [ ] checkboxes only in the Tests section.
Leave the line about Implemented status untouched — it is a guardrail, not a placeholder.

After Writing

Print the path of the new file and a one-line summary.
Suggest the obvious next step: ask to implement use case <NNN> when ready to build it.
Do not start implementing, do not commit, do not modify any other spec files. This skill's job ends at a written use case.

name: new-use-case description: Define a new use case by interviewing the user, then write a filled-in spec/use-cases/use-case-NNN-short-name.md. Use when the user wants to add, draft, or specify a new feature/use case.