Reference Files
references/use-case-template.md - Cockburn's Fully Dressed Use Case template with field descriptions and a worked example. Read this in Step 3 when writing individual use cases.
Overview
Based on Writing Effective Use Cases by Alistair Cockburn - the definitive reference on use case methodology. Cockburn's key insight is the goal level altitude metaphor: most use cases should be written at "sea level" (one user, one sitting, one goal). Writing too high (kite/cloud) produces vague summaries; too low (fish/clam) produces implementation detail disguised as requirements. The Actor-Goal List is the starting point, not the use case itself.
Workflow
Step 1: Build the Actor-Goal List
Before writing any use case, list every actor and their goals:
| Actor | Goal | Level |
|-------|------|-------|
| Customer | Place an order | Sea level (user goal) |
| Customer | Track shipment | Sea level |
| Warehouse clerk | Pick and pack order | Sea level |
| System (scheduler) | Generate daily reports | Sea level |
| Finance manager | Review quarterly revenue | Kite (summary) |
This list is the master index. Every sea-level goal becomes one use case.
Step 2: Set the scope and level
For each use case, declare:
- Scope: System under design (black-box) or component (white-box)?
- Level: Cloud (very high summary), Kite (summary), Sea level (user goal), Fish (subfunction), Clam (too low - avoid)
Most use cases should be sea level. If you find yourself writing fish-level steps, extract them into a sub-use case referenced via "includes."
Step 3: Write the Fully Dressed Use Case
Use Cockburn's template (see references/use-case-template.md):
USE CASE: [UC-number]: [Title - verb phrase]
PRIMARY ACTOR: [who triggers this]
GOAL: [what the actor is trying to achieve]
SCOPE: [system name]
LEVEL: [sea level / summary / subfunction]
PRECONDITIONS: [what must be true before this starts]
SUCCESS GUARANTEE: [what is true when this succeeds - this becomes acceptance criteria]
MAIN SUCCESS SCENARIO:
1. [Actor] [action]
2. [System] [response]
3. [Actor] [next action]
...
EXTENSIONS:
3a. [Condition]: [what happens instead]
3a1. [System] [alternate response]
3a2. Return to step [N] / Use case fails
Step 4: Write extensions for every branch
Extensions are where the real requirements live. For each step in the main scenario, ask:
- What could go wrong? (error extensions)
- What alternatives exist? (alternate flow extensions)
- What if the data is missing or invalid? (validation extensions)
Use the numbered branching notation: 3a, 3b, 3c for branches off step 3.
Step 5: Identify relationships between use cases
- Includes: Shared subfunctions (e.g., "Authenticate User" included by multiple use cases)
- Extends: Optional behavior that adds to the base use case
- Generalizes: Actor inheritance (e.g., "Premium Customer" generalizes "Customer")
Step 6: Validate with stakeholders
Walk through each use case with the primary actor or their representative. The main success scenario should sound like their description of a successful interaction.
Anti-Patterns
1. Writing at the wrong altitude
Bad: "The user clicks the Submit button" (clam level - too low, implementation detail).
Good: "The customer submits the order" (sea level - the goal, not the UI).
2. Extensions only for error cases
Bad: Only writing extensions for system failures.
Good: Extensions cover errors, alternatives, business rule variations, and edge cases.
3. Actor is "The User"
Bad: "The User performs actions." (Which user? What role?)
Good: Name the specific actor role: Customer, Warehouse Clerk, System Administrator.
4. Missing success guarantee
Bad: Use case with preconditions but no postconditions.
Good: Success guarantee states what is true after the use case completes - this directly becomes the acceptance criterion.
5. Monolithic use cases
Bad: A single use case that covers an entire workflow spanning 30+ steps.
Good: Break into sea-level use cases connected by includes/extends. Each should be 3-9 main steps.
Quality Checklist