Use Case Specification
beta · Family delivery-docs · Phase deliver · Sizes lean, full · ~3,600 tokens
Writes down, for one named primary actor and one goal, what the actor and the system do step by step when everything goes right, plus the alternative and exception paths that branch off at each point something can go another way. Elaborates one unit of product work a story or epic already names, between the point it is defined and the point acceptance criteria confirm it.
Self-grade against this before you share a use case specification. For the full reasoning, the
field-by-field provenance and where practitioners disagree, read
use-case-specification_companion.md. A fully worked instance
is use-case-specification_example.md.
When to use
Section titled “When to use”- One named actor has one goal, and the system’s behavior toward that goal needs writing down step by step, success included. A use case states a numbered main scenario plus the branches that can go another way; a single sentence or a pass/fail check will not carry that.
- The branches matter as much as the happy path, or more. Cockburn’s own account puts the use case’s greatest value in its alternative behaviors, not its main scenario, so reach for this type when a reader genuinely needs every detected deviation and where it ends up, not just the success story.
- This document will be elaborated into acceptance criteria or test cases downstream, and the person writing those needs a complete set of flows to derive them from, not a one-line summary.
- A project is running several related use cases that reference each other, need a shared stakeholder list, or need the same project annotation (priority, performance target, frequency) recorded once per use case rather than scattered across other documents.
When NOT to use
Section titled “When NOT to use”- The work is still a conversation starter, not a specified flow. A user story is a placeholder for a future conversation; use user stories and come back to a use case specification once the flow itself, not just the goal, needs writing down.
- You need field-level data definitions. A data dictionary or data map is the sourced home for what a field means and holds; use data-dictionary and keep this document free of data descriptions.
- You need to say how the system is built, not what it does from outside. This bundle templates the black-box reading only: the system’s behavior as seen from outside it. A reader who wants the internals wants sdd instead.
- You need to check whether a path already works, not specify what it should do. That is test-case; a use case is missing the data values a test case needs, and is not itself a test plan.
- You need a diagram or a board, not prose. A flow diagram or wireflow is this library’s nearest kept-out neighbor to this type; this bundle does not template a diagram, and that neighbor’s own placement in the library is still undecided.
- The whole thing is genuinely two to six sentences with no real branching. That is Cockburn’s own brief form, and it sits below anything this library templates. Write it as a note, not a document.
Pick a variant
Section titled “Pick a variant”| If the use case is… | Use |
|---|---|
| Low-ceremony, early-stage, or you need the main path and one line on each known deviation | lean |
| Formal, critical, or complex enough that a reviewer needs the full header, the stakeholder list, and every branch numbered and findable on its own | full |
Cockburn names three degrees of formality: brief, casual, and fully dressed. This library ships lean
for casual and full for fully dressed, and that mapping is this library’s own choice, not a reading
any source states. Cockburn’s own casual form is written as prose paragraphs; the lean template keeps
numbered steps instead, so lean is casual’s nearest equivalent in how much it covers, not in what shape
it takes. Lean drops the project annotation and the separate Extensions section the way casual drops
them, and asks for each known deviation in one line of prose inside the Main Success Scenario rather
than opening a separate section for them.
Growing lean into full. Cockburn’s own writing order moves from lower precision to higher: the actor’s name and goal first, then the main scenario, then the extension conditions, then the extension-handling steps. Follow the same order to grow a lean use case into a full one: add Scope and Level, Stakeholders and Interests, a separate Extensions section, Related Information, and Open Issues and Schedule, at the points the full template places them. Never reorder or rename the five sections the two variants share; the full variant is a strict superset of the lean one.
The rubric
Section titled “The rubric”Score each row 0, 1 or 2. Under 13 out of 18 on the full variant, a reviewer cannot confirm every path was actually considered, and the document comes back for another pass before it feeds acceptance criteria or tests downstream rather than going out as finished. The lean variant carries only the first five rows (maximum 10); the same consequence applies under 7.
| # | Criterion | 0 | 1 | 2 |
|---|---|---|---|---|
| 1 | Named for the goal | Titled after a feature, screen, or system area | Names a goal, but a different use case could plausibly share the same title | Names this actor’s specific goal as a verb phrase, and a different feature built the same way would not earn this title |
| 2 | Intention, not UI | A step names a screen element (“clicks Submit”, “a form appears”) | Mostly intention, with one or two interface words left in | Every step survives a redesign of the interface unchanged; you could swap the UI and not touch a word |
| 3 | Deviations handled | No deviation is handled, or one is named with no stated outcome | At least one deviation states both a condition and where it ends up | The branches took more drafting effort than the main scenario, and each names the condition the system actually detected and whether it rejoins, succeeds separately, or fails |
| 4 | Guarantee survives failure | Only a success condition is stated; failure is untreated | A failure condition is named, but only as an absence of failure (“nothing crashes”) | A positive, checkable condition holds on every exit, success included, stated separately from what additionally holds only on success |
| 5 | Preconditions state facts | Preconditions are blank, “none,” or restate the trigger | Preconditions list facts but blur into actions the actor takes once the case has started | Preconditions state only what is already true before the trigger; the trigger names one event, action or time-based, that starts the case |
| 6 | Black-box scope (full only) | Scope names internal components or how something is built | Scope names the system, but some internal detail leaks in | Scope names what the system does, seen from outside, with no implementation detail, and level is stated |
| 7 | Stakeholders beyond actor (full only) | No stakeholder beyond the primary actor is named | Stakeholders are listed, but their interests are generic enough to belong to any use case | At least one stakeholder who never touches the system directly is named, with a specific, checkable interest |
| 8 | Rules linked, not copied (full only) | A business rule’s text is copied inline, or a requirement shared by many use cases is restated here | Some rules are referenced by identifier; others are still restated | Every business rule a step enforces is referenced by identifier with where its text lives, and anything that applies to many use cases is linked, not copied |
| 9 | Open issues owned (full only) | An open issue is listed with no owner | An owner is named, but no date by which it must be resolved | Every open issue names both an owner and when it must be resolved by |
Which rows apply to what. Rows 6 through 9 grade sections the lean variant does not ship at all (Scope and Level, Stakeholders and Interests, Related Information, and Open Issues and Schedule), so scoring lean against them would penalize the choice of variant rather than the quality of the document.
| Variant | Rows that apply | Maximum | Score against |
|---|---|---|---|
| full | all 9 | 18 | 13 |
| lean | 1-5 (it carries none of Scope and Level, Stakeholders and Interests, a separate Extensions section, Related Information, or Open Issues and Schedule) | 10 | 7 |
Every cell above describes evidence, not a count. That is deliberate: a threshold cleared by adding items will be cleared by adding items rather than by improving the document, which is exactly what this library’s own research into defect-count gaming documents happening the moment a count becomes a target. If a cell can be satisfied without making the document better, it is written wrong.
Named anti-patterns
Section titled “Named anti-patterns”- UI standing in for intention. Writing what the screen does (“clicks Submit”) instead of what the actor is trying to accomplish. Cockburn names this, alongside including too many details, as the two most common and most costly mistakes a use case writer makes; a redesigned screen breaks every step written this way.
- The happy path gets all the care. Extensions, or the lean variant’s deviation lines, written as an afterthought, when the form’s own value sits in the branches rather than the main scenario.
- A detected condition that never says what was detected. “Something goes wrong: handle it” names no condition the system can actually check for and no outcome; the next reader has to guess both, and the branch cannot be verified against anything.
- An undefined or generic actor. “User” stands in for a role so broad the use case could be about almost anything, leaving no way to tell a novice’s path through the system from an expert’s.
- A step outside the goal. A step that happens before the stated precondition, after the stated guarantee, or that is otherwise unrelated to the actor’s goal is a sign the use case needs to split into more than one, not a sign it needs one more step.
- Inconsistent terms. The same thing named two different ways across steps and extensions, so a reader tracing a condition back to the step that detects it cannot tell whether it is the same thing.
- An unowned open issue. Recorded as a question with nobody responsible for closing it tends to stay open past the date the use case itself is due.
- A business rule restated instead of referenced. Copying a rule’s full text into the step that enforces it, or restating a requirement that applies to many use cases, instead of naming it by identifier and pointing at where its text actually lives.
The artifacts
Section titled “The artifacts”use-case-specification_template-lean.md · ~3,600 tokens
---title: "{{use_case_title}}"use_case_id: "{{use_case_id}}"primary_actor: "{{primary_actor}}"status: "{{status}}"doc_type: use-case-specificationsize: leansource_template: use-case-specificationsource_template_version: 0.1.0---
<!--CASUAL USE CASE SPECIFICATION. The five sections every fully dressed use case shares: the use case's titleand actor, its goal in context, what must be true before it starts and what starts it, the main successscenario, and what stays true however it ends. This is this library's own nearest equivalent of Cockburn'scasual form: it drops the project annotation and the separate Extensions section casual prose drops too,while keeping numbered steps where Cockburn's own casual form writes free prose paragraphs. Seeuse-case-specification_companion.md section 4 (Variants and sizing).
To grow this into the fully dressed form (see use-case-specification_template-full.md), ADD Scope andLevel, Stakeholders and Interests, Extensions, Related Information, and Open Issues and Schedule; neverrename or reorder the five sections below, because the full variant is a strict superset of this one.Cockburn's own writing order grows a use case the same way, from lower precision to higher: "PrecisionLevel 1: Primary actor's name and goal Precision Level 2: The use case brief, or the main success scenarioPrecision Level 3: The extension conditions Precision Level 4: The extension handling steps."
WHAT A USE CASE SPECIFICATION IS. Alistair Cockburn's own definition states the job directly: "A use casecaptures a contract between the stakeholders of a system about its behavior." It writes down, for oneprimary actor and one goal, a numbered main scenario plus the deviations that branch off it when somethinggoes another way. See use-case-specification_companion.md section 1.
ITS VALUE SITS IN THE BRANCHES, NOT THE HAPPY PATH. Cockburn again: "The greatest value of the use casedoes not lie in the main scenario, but in alternative behaviors." Even at this size, do not skip the knowndeviation lines inside the Main Success Scenario section below. See use-case-specification_companion.mdsection 1 and section 6, item 1.
IT IS NOT A TEST PLAN. Cockburn states the limit directly: "Use cases are not test plans or test cases.They are missing the data values needed for test cases." A use case states what the system must do; a testcase checks that it did. See use-case-specification_companion.md section 8.
IT DESCRIBES BEHAVIOR, NOT DESIGN. Cockburn's own distinction: "a black-box use case does not discuss theinternal structure of the system under discussion, while a white-box use case does." This bundle templatesthe black-box reading; write what the actor and the system do, never how the system is built to do it. Seeuse-case-specification_companion.md section 6, item 11.
HOW TO FILL THIS IN1. Read the comment under each heading: WHAT, WHY (with a companion pointer), ASK, GOOD, WEAK, TRAP.2. Replace each {{placeholder}}. Name the actor's goal in the title, write the Main Success Scenario at the level of the actor's intention, never the user interface, and give each known deviation one line of prose rather than inventing a separate Extensions section.3. If a section does not apply to this use case, write "N/A" and one line of why, rather than deleting it.4. Before you share it: self-grade against use-case-specification_guide.md, then DELETE every HTML comment. They are guidance, not content.-->
# {{use_case_title}}
## Title and Actor
<!-- WHAT The use case's name, stated as a short active verb phrase naming the goal, a unique identifier, and the primary actor whose goal this use case serves. WHY Cockburn's own 1998 template opens every use case with "Use Case: <number> <the name should be the goal as a short active verb phrase>", and the same header block names "Primary Actor: <a role name for the primary actor, or description>" a few fields further down. Three further sources independently ask for a unique identifier beyond a bare number: Wiegers' "Give each use case a unique numeric identifier, in hierarchical form: X.Y.", NYU's "Use Case ID: {This should be coded to identify the owning team and the level of the use case}", and Notre Dame's "Each use case should have a unique identifier that can be used for quick reference and traceability." Deep dive: use-case-specification_companion.md section 3 (Title and Actor). ASK What is the actor's goal, stated as a short active verb phrase? What identifier does this use case carry, so it can be found again? Who is the primary actor: a role name, or a short description if no settled role name exists? GOOD "Title: Reset a forgotten password. ID: UC-07. Primary Actor: Account Holder, an actor who has lost access to their own account and wants back in without contacting support." WEAK "Title: Account Settings. ID: (none). Primary Actor: user." (not a goal phrase, no identifier, and "user" is a role so generic the use case could be about almost anything) TRAP Naming the use case after a feature or a screen instead of the actor's goal. "Account Settings" is a part of the system; "Reset a forgotten password" is what the actor is trying to accomplish, and the latter is what Cockburn's own field asks for. -->
**Use Case ID:** {{use_case_id}}
**Primary Actor:** {{primary_actor}} - {{primary_actor_description}}
## Goal in Context
<!-- WHAT A longer statement of the actor's goal than the title line gives, including the circumstances under which the goal normally arises. WHY Cockburn's 1998 template carries this field under the same name used here: "Goal in Context: <a longer statement of the goal, if needed>". His later draft renames it "Context of use" and adds a question this ASK keeps: "<a longer statement of the goal, if needed, its normal occurrence conditions>". This is the field the family's own "elaborates" verb is organized around: the goal that every other section serves. Deep dive: use-case-specification_companion.md section 3 (Goal in Context). ASK What is the actor trying to accomplish, in a sentence or two beyond the title? Under what circumstances does this goal typically arise: a regular habit, a one-time event, a response to something else happening? GOOD "An account holder who has forgotten their password can no longer sign in to any of their own accounts. They want to regain access on their own, without calling support or waiting for a human to intervene." WEAK "The actor wants to use the reset feature." (restates the title without adding the circumstance that brings the actor to this goal) TRAP Writing a one-line paraphrase of the title instead of the longer statement the field asks for. If this section adds nothing the title did not already say, the field has not done its job. -->
{{goal_in_context}}
## Preconditions and Trigger
<!-- WHAT What must already be true of the world before this use case can start, and the event that actually starts it. WHY Cockburn's 1998 template: "Preconditions: <what we expect is already the state of the world>" and "Trigger: <the action upon the system that starts the use case, may be time event>". Wiegers asks the same thing in different words: "List any activities that must take place, or any conditions that must be true, before the use case can be started." RUP defines the term directly: "A precondition of a use case is the state of the system that must be present prior to a use case being performed." Deep dive: use-case-specification_companion.md section 3 (Preconditions and Trigger). ASK What must already be true before this use case can begin? What single event starts it: an action the actor takes, or a time event the system itself raises? GOOD "Preconditions: the account already exists and has a verified email address on file. Trigger: the account holder indicates, from the sign-in screen, that they cannot sign in with their current password." WEAK "Preconditions: none. Trigger: the user does something." (a use case with genuinely no preconditions is rare, and "does something" names no event) TRAP Writing a step of the scenario itself as a precondition. A precondition is a fact about the world before the use case starts, not an action the actor takes once it has; the 1998 field's own wording distinguishes "what we expect is already the state of the world" from the trigger that starts the clock. A trigger can also be a time event rather than an action; do not assume every use case starts with someone clicking something. -->
**Preconditions:** {{preconditions}}
**Trigger:** {{trigger}}
## Main Success Scenario
<!-- WHAT The numbered sequence of steps, from trigger to goal delivery, that plays out when nothing goes wrong, plus one line of prose for each known deviation. WHY Cockburn's 1998 template's own placeholder reads "<put here the steps of the scenario from trigger to goal delivery, and any cleanup after>", and RUP names the same section "2.1 Basic Flow". Cockburn's own writing rule asks for "one column of text (not a table)" and no branching inside it: a step that branches belongs in Extensions in the full template. This library's own lean variant has no separate Extensions section; it asks for each known deviation in one line of prose here instead, because the casual form Cockburn describes is "likely to be less rigorous in its description than a fully dressed use case" while its value still sits in its deviations, per Cockburn's own account: "The greatest value of the use case does not lie in the main scenario, but in alternative behaviors." Deep dive: use-case-specification_companion.md section 3 (Main Success Scenario) and section 4 (Variants and sizing). ASK What is the shortest sequence of steps that gets the actor from the trigger to the goal, with nothing going wrong? For each step, does it show a goal succeeding rather than a screen rendering? Does the actor and the system alternate, each step a response to the one before it? In which ways can this scenario go another way, and how does the system handle each one, in a line of prose apiece? GOOD "1. The account holder indicates they cannot sign in with their current password. 2. The account holder confirms which account this is, by email address. 3. The system sends a time-limited link to that address that lets the account holder set a new password. 4. The account holder follows the link and sets a new password. Known deviations: if the email address does not match any account, the system shows the same generic message rather than revealing whether an account exists. If the link has expired when it is followed, the system offers to send a new one." WEAK "1. User clicks "Forgot password?". 2. A form appears. 3. User clicks Submit." with no deviation lines at all (names screen elements, not the actor's intention, and skips the branch this library's own research found to be where a use case's real value sits) TRAP Naming a user-interface element instead of the actor's intention. Cockburn's own step-writing rule: "Highlight the actor's intention, not the user interface details." Keep each step to one activity, stop between three and nine steps, and do not let a deviation line become a second full scenario; if a deviation genuinely needs its own numbered handling steps, that is the signal to grow this use case into the full variant instead of stacking lines here. -->
1. {{step_1}}2. {{step_2}}3. {{step_3}}
**Known deviations:**
- {{known_deviation}}
## Minimal and Success Guarantees
<!-- WHAT What stays true no matter how the use case ends, paired with what is additionally true only when it ends successfully. WHY Cockburn's 1998 template carried a single "Failed End Condition: <the state of the world if goal abandoned>", a property of the failure exit alone. His later draft replaces it with two paired fields, and this is a change of meaning, not just a rename: "Minimal Guarantees: <how the interests are protected under all exits>" beside "Success Guarantees: <the state of the world if goal succeeds>". OpenUP's checklist states the distinction as two separate, checkable properties: "(A Minimal Guarantee represents a condition that will be true when the use case ends, regardless of how it terminates.)" against "(A Success Guarantee represents a condition that will be true when the use case ends successfully, regardless of which path it takes.)" Deep dive: use-case-specification_companion.md section 3 (Minimal and Success Guarantees). ASK What must stay true however this use case ends, success or failure alike? What is additionally true only when it ends successfully? GOOD "Minimal Guarantees: the account holder's current password keeps working until a new one is confirmed, so an abandoned or failed reset never locks them out. Success Guarantees: the account has a new password, and every other active session for that account is signed out." WEAK "Minimal Guarantees: the system doesn't crash. Success Guarantees: it worked." (neither is a checkable condition of the world) TRAP Writing only a success condition and treating "it didn't fail" as the minimal guarantee. A minimal guarantee is a positive statement about what is protected on every exit, including a failed one, not an absence of failure. -->
**Minimal Guarantees:** {{minimal_guarantees}}
**Success Guarantees:** {{success_guarantees}}use-case-specification_template-full.md · ~6,350 tokens
---title: "{{use_case_title}}"use_case_id: "{{use_case_id}}"primary_actor: "{{primary_actor}}"status: "{{status}}"doc_type: use-case-specificationsize: fullsource_template: use-case-specificationsource_template_version: 0.1.0---
<!--FULLY DRESSED USE CASE SPECIFICATION. Ten sections, in a fixed order: the use case's title and actor, itsgoal in context, its scope and level, its stakeholders and interests, what must be true before it startsand what starts it, the main success scenario, the extensions that branch off it, what stays true howeverit ends, the project annotation a fully dressed use case carries beyond its header, and its open issues andschedule. Use this variant for a use case formal or critical enough that a reviewer needs the full header,the stakeholder list, and every extension numbered and findable on its own. Seeuse-case-specification_companion.md section 4 (Variants and sizing).
This is a STRICT SUPERSET of use-case-specification_template-lean.md: the lean variant's five sectionscarry the same name and the same order as five of these ten. If you are growing a lean use case into thisone, ADD Scope and Level, Stakeholders and Interests, Extensions, Related Information, and Open Issues andSchedule at the points this file places them; do not reorder the five sections the two variants share.
WHAT A USE CASE SPECIFICATION IS. Alistair Cockburn's own definition states the job directly: "A use casecaptures a contract between the stakeholders of a system about its behavior." It writes down, for oneprimary actor and one goal, a numbered main scenario plus the lettered extensions that branch off it whensomething goes another way. See use-case-specification_companion.md section 1.
ITS VALUE SITS IN THE BRANCHES, NOT THE HAPPY PATH. Cockburn again: "The greatest value of the use casedoes not lie in the main scenario, but in alternative behaviors." Spend more care on Extensions than on theMain Success Scenario; the scenario is usually the easier half to write. Seeuse-case-specification_companion.md section 1 and section 6, item 1.
IT IS NOT A TEST PLAN. Cockburn states the limit directly: "Use cases are not test plans or test cases.They are missing the data values needed for test cases." A use case states what the system must do; a testcase checks that it did. See use-case-specification_companion.md section 8.
IT DESCRIBES BEHAVIOR, NOT DESIGN. Cockburn's own distinction: "a black-box use case does not discuss theinternal structure of the system under discussion, while a white-box use case does." This bundle templatesthe black-box reading; write what the actor and the system do, never how the system is built to do it. Seeuse-case-specification_companion.md section 6, item 11.
HOW TO FILL THIS IN1. Read the comment under each heading: WHAT, WHY (with a companion pointer), ASK, GOOD, WEAK, TRAP; a section that records more than one entry adds PRIORITY and ROW HINT.2. Replace each {{placeholder}}. Name the actor's goal in the title, and write the Main Success Scenario at the level of the actor's intention, never the user interface.3. If a section does not apply to this use case, write "N/A" and one line of why, rather than deleting it.4. Before you share it: self-grade against use-case-specification_guide.md, then DELETE every HTML comment. They are guidance, not content.-->
# {{use_case_title}}
## Title and Actor
<!-- WHAT The use case's name, stated as a short active verb phrase naming the goal, a unique identifier, and the primary actor whose goal this use case serves. WHY Cockburn's own 1998 template opens every use case with "Use Case: <number> <the name should be the goal as a short active verb phrase>", and the same header block names "Primary Actor: <a role name for the primary actor, or description>" a few fields further down. Three further sources independently ask for a unique identifier beyond a bare number: Wiegers' "Give each use case a unique numeric identifier, in hierarchical form: X.Y.", NYU's "Use Case ID: {This should be coded to identify the owning team and the level of the use case}", and Notre Dame's "Each use case should have a unique identifier that can be used for quick reference and traceability." Deep dive: use-case-specification_companion.md section 3 (Title and Actor). ASK What is the actor's goal, stated as a short active verb phrase? What identifier does this use case carry, so it can be found again? Who is the primary actor: a role name, or a short description if no settled role name exists? GOOD "Title: Reset a forgotten password. ID: UC-07. Primary Actor: Account Holder, an actor who has lost access to their own account and wants back in without contacting support." WEAK "Title: Account Settings. ID: (none). Primary Actor: user." (not a goal phrase, no identifier, and "user" is a role so generic the use case could be about almost anything) TRAP Naming the use case after a feature or a screen instead of the actor's goal. "Account Settings" is a part of the system; "Reset a forgotten password" is what the actor is trying to accomplish, and the latter is what Cockburn's own field asks for. -->
**Use Case ID:** {{use_case_id}}
**Primary Actor:** {{primary_actor}} - {{primary_actor_description}}
## Goal in Context
<!-- WHAT A longer statement of the actor's goal than the title line gives, including the circumstances under which the goal normally arises. WHY Cockburn's 1998 template carries this field under the same name used here: "Goal in Context: <a longer statement of the goal, if needed>". His later draft renames it "Context of use" and adds a question this ASK keeps: "<a longer statement of the goal, if needed, its normal occurrence conditions>". This is the field the family's own "elaborates" verb is organized around: the goal that every other section serves. Deep dive: use-case-specification_companion.md section 3 (Goal in Context). ASK What is the actor trying to accomplish, in a sentence or two beyond the title? Under what circumstances does this goal typically arise: a regular habit, a one-time event, a response to something else happening? GOOD "An account holder who has forgotten their password can no longer sign in to any of their own accounts. They want to regain access on their own, without calling support or waiting for a human to intervene." WEAK "The actor wants to use the reset feature." (restates the title without adding the circumstance that brings the actor to this goal) TRAP Writing a one-line paraphrase of the title instead of the longer statement the field asks for. If this section adds nothing the title did not already say, the field has not done its job. -->
{{goal_in_context}}
## Scope and Level
<!-- WHAT The system under design, stated as a black box, and how large a unit of work this use case covers relative to the actor's own goals. WHY Cockburn's own draft prints both fields together: "Scope: <design scope, what system is being considered black-box under design>" and "Level: <one of: Summary, User-goal, Subfunction>". The draft also names the design-scope axis directly: "A business use case has the enterprise as its design scope." against "A system use case has a computer system as its design scope." Deep dive: use-case-specification_companion.md section 3 (Scope and Level) and section 6, item 4. ASK What system is this use case about, stated as a black box (what it does, not how it is built)? Is this a user-goal use case (one person, one sitting, roughly two to twenty minutes), a summary use case that bundles several user goals, or a subfunction use case that exists only because a user-goal use case needs it? GOOD "Scope: the account system's sign-in and credential-recovery functions, considered as a black box. Level: user-goal (one person, one sitting)." WEAK "Scope: the system. Level: medium." (names no actual boundary, and "medium" is not one of the three stated levels) TRAP Describing the system's internals instead of its boundary. Cockburn's own rule: "Recall, in the following, that a black-box use case does not discuss the internal structure of the system under discussion, while a white-box use case does." This bundle templates the black-box reading only; see the preamble above. -->
**Scope:** {{scope}}
**Level:** {{level}}
## Stakeholders and Interests
<!-- WHAT Everyone with a vested interest in how this use case behaves, including anyone who never interacts with the system directly, and what each of them wants from it. WHY This section rests on Cockburn's own later work alone, at medium confidence: his 1998 template never mentions a stakeholder, but his draft carries "Stakeholders & Interests: <list of stakeholders and key interests in the use case>", and a stakeholder is, in the draft's own words, "someone with a vested interest in the behavior of the use case, even if they never interact directly with the system." His own writing process makes the rest of the document answer to this list: "7. Capture stakeholders and interests, preconditions and guarantees. The system will ensure the preconditions and guarantee the interests." Deep dive: use-case-specification_companion.md section 3 (Stakeholders and Interests). ASK Who has a stake in how this use case behaves, beyond the primary actor? What does each one want from it? List a stakeholder even if they never touch the system themselves. PRIORITY List every stakeholder whose interest could change how a step or a guarantee is written, even one who never interacts with the system; an omitted stakeholder's interest has no way to reach the Main Success Scenario or the Minimal Guarantees later. ROW HINT A good row names a stakeholder and a specific, checkable interest. A weak row names a role with no stated interest, or an interest so broad it could belong to any use case. GOOD | Support Team | Wants the volume of password-reset calls to go down, not up | WEAK | Management | Cares about the product | TRAP Listing only the primary actor here. The primary actor already has their own field above; this section exists for everyone else with a stake, the people a step or a guarantee could affect without ever appearing in the Main Success Scenario. -->
| Stakeholder | Interest ||---|---|| {{stakeholder}} | {{stakeholder_interest}} |
## Preconditions and Trigger
<!-- WHAT What must already be true of the world before this use case can start, and the event that actually starts it. WHY Cockburn's 1998 template: "Preconditions: <what we expect is already the state of the world>" and "Trigger: <the action upon the system that starts the use case, may be time event>". Wiegers asks the same thing in different words: "List any activities that must take place, or any conditions that must be true, before the use case can be started." RUP defines the term directly: "A precondition of a use case is the state of the system that must be present prior to a use case being performed." Deep dive: use-case-specification_companion.md section 3 (Preconditions and Trigger). ASK What must already be true before this use case can begin? What single event starts it: an action the actor takes, or a time event the system itself raises? GOOD "Preconditions: the account already exists and has a verified email address on file. Trigger: the account holder indicates, from the sign-in screen, that they cannot sign in with their current password." WEAK "Preconditions: none. Trigger: the user does something." (a use case with genuinely no preconditions is rare, and "does something" names no event) TRAP Writing a step of the scenario itself as a precondition. A precondition is a fact about the world before the use case starts, not an action the actor takes once it has; the 1998 field's own wording distinguishes "what we expect is already the state of the world" from the trigger that starts the clock. A trigger can also be a time event rather than an action; do not assume every use case starts with someone clicking something. -->
**Preconditions:** {{preconditions}}
**Trigger:** {{trigger}}
## Main Success Scenario
<!-- WHAT The numbered sequence of steps, from trigger to goal delivery, that plays out when nothing goes wrong. WHY Cockburn's 1998 template's own placeholder reads "<put here the steps of the scenario from trigger to goal delivery, and any cleanup after>", and RUP names the same section "2.1 Basic Flow". Cockburn's own writing rule asks for "one column of text (not a table)" and no branching inside it: steps that branch belong in Extensions. Deep dive: use-case-specification_companion.md section 3 (Main Success Scenario). ASK What is the shortest sequence of steps that gets the actor from the trigger to the goal, with nothing going wrong? For each step, does it show a goal succeeding rather than a screen rendering? Does the actor and the system alternate, each step a response to the one before it? GOOD "1. The account holder indicates they cannot sign in with their current password. 2. The account holder confirms which account this is, by email address. 3. The system sends a time-limited link to that address that lets the account holder set a new password. 4. The account holder follows the link and sets a new password." WEAK "1. User clicks "Forgot password?". 2. A form appears. 3. User clicks Submit." (names screen elements, not the actor's intention; a redesigned form breaks every step) TRAP Naming a user-interface element instead of the actor's intention. Cockburn's own step-writing rule: "Highlight the actor's intention, not the user interface details." Keep each step to one activity, written in the active voice, and stop between three and nine steps; Cockburn's own account is that he is "yet to write a main success scenario longer than nine steps." A step that needs an "if" belongs in Extensions below, not here. -->
1. {{step_1}}2. {{step_2}}3. {{step_3}}
## Extensions
<!-- WHAT The branches off the main success scenario, each naming the condition that triggers it, how the system handles it, and where it ends up: back in the main scenario, a separate success, or a failure. WHY Cockburn's 1998 template's own placeholder for a branch is "<step altered> <condition> : <action or sub.use case>", and his draft gives the numbering convention this section follows: "the numbering convention in the extensions sections involving combinations of digits and letters (e.g., 2a, 2a1, 2a2 and so on)". RUP's own "2.2 Alternative Flows" and the jointly authored foundation's framing, "A list of all the special cases, alternative paths, optional steps, and errors that need to be handled," both keep alternative and exception paths in one section rather than splitting them, which is the reading this bundle follows. Deep dive: use-case-specification_companion.md section 3 (Extensions) and section 6, item 8. ASK What can go another way at each step, that the system itself can detect? For each one: what handles it, and does it rejoin the main scenario, end in a separate success, or end in failure? Did you brainstorm exhaustively before writing the handling steps, per Cockburn's own order: "9. Brainstorm and exhaustively list the extension conditions. Include all that the system can detect and must handle." then "10. Write the extension-handling steps." PRIORITY Spend more effort here than on the Main Success Scenario above; per the preamble, the greatest value of a use case lies in its alternative behaviors, not its happy path. ROW HINT A good row names the branch point and letter (3a), states a condition the system can actually detect, and names where the branch ends up. A weak row has a vague condition such as "error occurs" with no stated outcome. GOOD | 2a | The email address does not match any account | Show the same generic "a link has been sent if this matches an account" message | Ends without revealing whether the account exists | WEAK | 3a | Something goes wrong | Handle it | (unknown) | TRAP Describing an error without saying what the system does about it. Sehlhorst names this directly: "Unanticipated error conditions. The error conditions are explicitly called out in a formal use case as exception courses. When we fail to think about how things can go wrong, we take a bad situation (an error) and make it worse by leaving our users with no reasonable way to deal with the errors." Every actor step in the main scenario should have a system response; the same discipline applies to every extension. -->
| Extension | Condition | Handling | Outcome ||---|---|---|---|| {{extension_id}} | {{extension_condition}} | {{extension_handling}} | {{extension_outcome}} |
## Minimal and Success Guarantees
<!-- WHAT What stays true no matter how the use case ends, paired with what is additionally true only when it ends successfully. WHY Cockburn's 1998 template carried a single "Failed End Condition: <the state of the world if goal abandoned>", a property of the failure exit alone. His later draft replaces it with two paired fields, and this is a change of meaning, not just a rename: "Minimal Guarantees: <how the interests are protected under all exits>" beside "Success Guarantees: <the state of the world if goal succeeds>". OpenUP's checklist states the distinction as two separate, checkable properties: "(A Minimal Guarantee represents a condition that will be true when the use case ends, regardless of how it terminates.)" against "(A Success Guarantee represents a condition that will be true when the use case ends successfully, regardless of which path it takes.)" Deep dive: use-case-specification_companion.md section 3 (Minimal and Success Guarantees). ASK What must stay true however this use case ends, success or failure alike, to protect the stakeholders' interests? What is additionally true only when it ends successfully? GOOD "Minimal Guarantees: the account holder's current password keeps working until a new one is confirmed, so an abandoned or failed reset never locks them out. Success Guarantees: the account has a new password, and every other active session for that account is signed out." WEAK "Minimal Guarantees: the system doesn't crash. Success Guarantees: it worked." (neither is a checkable condition of the world, and neither names what the earlier Stakeholders list cares about) TRAP Writing only a success condition and treating "it didn't fail" as the minimal guarantee. A minimal guarantee is a positive statement about what is protected on every exit, including a failed one, not an absence of failure; a template that asks only for success and failure end conditions never asks what must stay true however the case ends, which is exactly the gap this pairing closes. -->
**Minimal Guarantees:** {{minimal_guarantees}}
**Success Guarantees:** {{success_guarantees}}
## Related Information
<!-- WHAT An open slot for whatever project-specific facts this use case needs beyond its core fields: priority, performance target, frequency, a channel or device difference that would otherwise bifurcate the scenario, secondary actors, and any superordinate or subordinate use case. WHY Cockburn's 1998 template closes with exactly this block: "RELATED INFORMATION (optional) Priority: <how critical to your system / organization> Performance Target: <the amount of time this use case should take> Frequency: <how often it is expected to happen> Superordinate Use Case: <optional, name of use case that includes this one> Subordinate Use Cases: <optional, depending on tools, links to sub.use cases> Channel to primary actor: <e.g. interactive, static files, database> Secondary Actors: <list of other systems needed to accomplish use case>". A note on that template says his book renamed the sub-variations field to "Technology and Data Variations List", the line for a channel or device difference, which lets the Main Success Scenario above stay at the level of intention. Deep dive: use-case-specification_companion.md section 3 (Related Information). ASK How critical is this use case, and how long should it take? How often does it happen? Does any secondary actor, system, or device variation belong here instead of inside the scenario? Does this use case include or get included by another one? Does any step enforce a business rule? Reference each rule by its identifier and say where its text lives, rather than copying it here. A nonfunctional requirement shared by many use cases is better linked from here than restated: OpenUP asks, "Are these nonfunctional requirements applicable to many use cases?" and answers, "consider capturing them in the supporting Requirements Specification to simplify maintenance". GOOD "Priority: high (a core account-recovery path). Performance Target: the reset email arrives within two minutes at p95 (illustrative). Frequency: rare per account, constant in aggregate across all accounts. Technology and Data Variations: the request can also start from the mobile app. Secondary Actors: the email delivery service. Superordinate/Subordinate Use Cases: none." WEAK "Priority: important." (no performance target, no frequency, nothing a reader could check against later) TRAP Copying a performance target or priority that belongs to many use cases into this one instead of linking to where it is set once. OpenUP's own rule names exactly this failure. -->
**Priority:** {{priority}}
**Performance Target:** {{performance_target}}
**Frequency:** {{frequency}}
**Technology and Data Variations:** {{technology_and_data_variations}}
**Secondary Actors:** {{secondary_actors}}
**Superordinate/Subordinate Use Cases:** {{related_use_cases}}
## Open Issues and Schedule
<!-- WHAT Unresolved questions this use case still carries, each with an owner, and the release or date it is due by. WHY Cockburn's 1998 template closes with both fields: "OPEN ISSUES (optional) <list of issues about this use cases awaiting decisions>" and "SCHEDULE Due Date: <date or release of deployment>". Wiegers asks for the same content in different words: "List any additional comments about this use case or any remaining open issues or TBDs (To Be Determineds) that must be resolved." This is the one section with no corroboration from Cockburn's own later draft, which carries neither field. Deep dive: use-case-specification_companion.md section 3 (Open Issues and Schedule). ASK What is still unresolved about this use case? Who owns resolving each open issue, not just that one exists? What release or date is this use case due by? PRIORITY Name an owner for every open issue; an issue with no owner has no path to resolution. ROW HINT A good row names the open question, who owns it, and when it must be resolved by. A weak row names only that something is undecided. GOOD | Should a locked-out account auto-unlock once the reset completes, or stay locked pending a separate security review? | Security Lead | Before next release | WEAK | It's not clear what happens on failure | (unowned) | TRAP Recording an open issue with no owner. An unowned open issue tends to stay open past the date this use case is due, because no one is accountable for closing it. -->
| Open Issue | Owner | Needed By ||---|---|---|| {{open_issue}} | {{open_issue_owner}} | {{open_issue_deadline}} |
**Due Date:** {{due_date}}use-case-specification_example.md
---title: "Set a Default Saved View"use_case_id: "UC-SV-04"primary_actor: "Recurring Analyst"doc_type: use-case-specificationsize: fullowner: "Priya Nair (PM, Reporting)"status: "in-review"doc_version: "0.1.0"created: "2026-06-20"updated: "2026-06-30"related_links: - "Story: set a default saved view (user-stories_example.md)" - "PRD: Saved Views (prd_example.md)"source_template: use-case-specificationsource_template_version: 0.1.0---
> **Worked example.** A filled `use-case-specification`, full variant, elaborating the> [set a default saved view](../user-stories/user-stories_example.md) story from this library's own> "Saved Views" chain, the same work the> [acceptance criteria](../acceptance-criteria/acceptance-criteria_example.md) that follow it go on to> confirm. `use-case-specification` joined the `delivery-docs` family on 2026-10-15 under> [ADR 0072](../../docs/internal/decisions/0072-use-case-specification-joins-delivery-docs.md), and sits> in the chain between the story it elaborates and the acceptance criteria that confirm it. It is dated> **created 2026-06-20**, after the story entered review on 2026-06-18 and before the acceptance criteria> that follow it were drafted on 2026-06-22, so its related links name the story and the PRD but not> the acceptance criteria, which did not yet exist on this document's own created date; **updated> 2026-06-30**, the same date every document in this chain carries as its latest revision, and the revision> that took the acceptance criteria's performance target. The priority traces to the PRD's FR-3. The> frequency below is illustrative: plausible for this document and labeled where it appears, not drawn> from a real company.
# Set a Default Saved View
## Title and Actor
**Use Case ID:** UC-SV-04
**Primary Actor:** Recurring Analyst - an internal or customer analyst who returns to the samedashboards daily or weekly and works within a stable set of filters.
## Goal in Context
A recurring analyst who already has one or more saved views for a dashboard wants one of them to loadautomatically every time they return to it, instead of re-selecting a view or starting from thedashboard's generic default state on every visit. The goal arises out of a daily or weekly habit: once ananalyst has saved the filters, date range and columns they actually work from, choosing among severalsaved views on every single visit is itself a small repeated cost, the same re-filtering tax that savinga view in the first place was meant to remove. Setting a default lets that habit stop costing anythingafter the first time it is set, and the analyst may change which view is the default again later if theslice they work from changes.
## Scope and Level
**Scope:** Dashboards in Acme Analytics, considered as a black box: which one of a user's own savedviews, if any, is marked as the view that loads automatically when that user opens a given dashboard. Howa dashboard renders the data inside a view, and how a view is captured and saved in the first place, sitoutside this use case's own scope.
**Level:** User-goal. Setting the default takes one sitting; step 4 is its payoff, on the analyst'snext visit.
## Stakeholders and Interests
| Stakeholder | Interest ||---|---|| Team Lead | Wants a personal default one analyst sets for themselves to never change what any other user of the same dashboard sees, since whether a Team Lead can set a team-wide default for everyone is still an open question for this dashboard || Other users of the same dashboard | Want their own default, or the absence of one, to stay exactly as it was, regardless of what any other user marks as their own default |
## Preconditions and Trigger
**Preconditions:** The recurring analyst already has at least one saved view for this dashboard; thesave-view story is a sequenced prerequisite for this one. The per-user preferences store, which thePlatform team shipped in Q1, already holds that analyst's existing saved views for this dashboard.
**Trigger:** The recurring analyst, from the dashboard's Views control, chooses one of their existingsaved views to become this dashboard's default.
## Main Success Scenario
1. The recurring analyst chooses one of their saved views for this dashboard to become their default.2. The system un-marks whichever saved view currently holds default status for this dashboard for that analyst.3. The system marks the chosen view as the recurring analyst's default for this dashboard.4. The next time the recurring analyst opens this dashboard, the system loads it already in the default view's filters, date range and columns applied, instead of the dashboard's generic default state.
## Extensions
| Extension | Condition | Handling | Outcome ||---|---|---|---|| 2a | The recurring analyst has no default for this dashboard yet, so the dashboard still opens in its generic default state | Nothing needs un-marking | Rejoins the main scenario at step 3 || 4a | The default view references a filter that has since been deleted | The system loads the still-valid filters and shows a clear "some filters in this view no longer exist" message, with a way to fix and re-save | Ends in a separate success; the analyst sees the dashboard and knows exactly what to fix |
## Minimal and Success Guarantees
**Minimal Guarantees:** However the attempt ends, no other user's default for this dashboard changes,which is the interest both stakeholders above hold, and this analyst never holds more than one defaultfor it. If the attempt stops partway, the dashboard still opens, in its generic default state if nodefault of theirs survived.
**Success Guarantees:** The chosen view is this recurring analyst's one default for this dashboard, andthe view that held that status before no longer does.
## Related Information
**Priority:** High. FR-3 is a Must-priority requirement for the Phase 1 release, which ships privateviews (FR-1 to FR-3, FR-5) behind a feature flag.
**Performance Target:** Loading the default view on dashboard open completes within 1 second at p95(illustrative target, the same one the acceptance criteria carry).
**Frequency:** Not measured directly. The only related figure is how often a recurring analyst visits adashboard at all, daily or weekly, not how often any one of them changes their default(illustrative, inferred from that visiting cadence rather than drawn from a measurement of this use caseitself).
**Technology and Data Variations:** None known.
**Secondary Actors:** The per-user preferences store, the Q1 Platform-team service that records andreturns which saved view is marked default for a given user and dashboard.
**Superordinate/Subordinate Use Cases:** None known.
## Open Issues and Schedule
| Open Issue | Owner | Needed By ||---|---|---|| Should a Team Lead be able to set a team default for a dashboard, or should only personal defaults ever exist? | Priya Nair | Before Phase 2 |
**Due Date:** Phase 1 (private views only, behind a feature flag).Provenance
Section titled “Provenance”The reasoning, the history and every source, in the repository:
- Companion - the long-form argument: why these sections, where the sources disagree, and what the bundle refuses to claim
- History - what changed in this bundle, and when
- Research log - every source consulted, with what each one actually supports
- Catalog metadata - the machine-readable record this page is generated from
Catalog record: 10 sections across 1 format(s), methodology methodology-agnostic, typically owned by BA.