Skip to content

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.


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


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.


  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. 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.

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-specification
size: lean
source_template: use-case-specification
source_template_version: 0.1.0
---
<!--
CASUAL USE CASE SPECIFICATION. The five sections every fully dressed use case shares: the use case's title
and actor, its goal in context, what must be true before it starts and what starts it, the main success
scenario, and what stays true however it ends. This is this library's own nearest equivalent of Cockburn's
casual 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. See
use-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 and
Level, Stakeholders and Interests, Extensions, Related Information, and Open Issues and Schedule; never
rename 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: "Precision
Level 1: Primary actor's name and goal Precision Level 2: The use case brief, or the main success scenario
Precision 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 case
captures a contract between the stakeholders of a system about its behavior." It writes down, for one
primary actor and one goal, a numbered main scenario plus the deviations that branch off it when something
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 case
does not lie in the main scenario, but in alternative behaviors." Even at this size, do not skip the known
deviation lines inside the Main Success Scenario section below. See use-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 test
case 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 the
internal structure of the system under discussion, while a white-box use case does." This bundle templates
the black-box reading; write what the actor and the system do, never how the system is built to do it. See
use-case-specification_companion.md section 6, item 11.
HOW TO FILL THIS IN
1. 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}}

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.