Use Cases

Writing Use Cases Developers Love

Apply the Cockburn fully-dressed template with goal levels, business rules, and concrete worked examples across real-world features.

The Cockburn Fully-Dressed Template

Alistair Cockburn defined the "fully-dressed" use case format with these fields:

  • Title: Short verb phrase describing the goal ("Place Order", "Reset Password")
  • Scope: The system being designed
  • Level: The goal level (see below)
  • Primary Actor: Who initiates
  • Stakeholders and Interests: Everyone affected and what they need
  • Preconditions: Must be true before start
  • Success Guarantee (Postconditions): True after success
  • Main Success Scenario: Numbered happy path steps
  • Extensions: Alternate paths with labels like 3a, 5b
  • Special Requirements: Performance, security, usability constraints
  • Technology and Data Variations: Implementation notes
  • Frequency of Occurrence: How often this is invoked
  • Open Issues: Questions not yet resolved

Cockburn's Goal Levels

Cockburn distinguishes three levels of goal:

Kite level (blue): Business goals. "Increase repeat purchases." "Reduce support tickets." These are too abstract to implement directly.

Sea level (white): User goals. The primary level for use cases. "Place an order." "Reset password." These describe what users actually come to the system to do.

Fish level (grey): Sub-functions. Steps within a sea-level use case. "Validate credit card number." "Calculate shipping cost." These are too granular for standalone use cases — they belong as steps or extensions.

Write use cases at sea level. Reference fish-level behaviors as steps.

Worked Example 1: E-Commerce Checkout

Use Case: Customer Completes Purchase

*Level: Sea (user goal)*

*Actor: Authenticated Customer*

*Preconditions:* Cart has at least one in-stock item. Customer is logged in.

*Postconditions:* Order record created. Inventory decremented. Confirmation email queued.

*Main Success Scenario:*

  1. Customer clicks "Proceed to Checkout" from cart
  2. System displays order summary with items, quantities, and subtotal
  3. Customer selects shipping address (or enters new one)
  4. Customer selects payment method from saved cards (or enters new card)
  5. Customer selects shipping speed; system displays estimated delivery date and final total
  6. Customer clicks "Place Order"
  7. System charges payment method
  8. System creates order record with status "Processing"
  9. System decrements inventory for each item
  10. System queues order confirmation email
  11. System displays order confirmation page with order number

*Extensions:*

  • 3a. No saved addresses: system shows address entry form
  • 4a. No saved payment methods: system shows card entry form with Stripe Elements
  • 7a. Payment declined: system shows "Your payment could not be processed. Please check your card details." Order is not created.
  • 7b. Network error during charge: system shows "Something went wrong. Your card was not charged." and logs the error for retry
  • 9a. Item goes out of stock between cart add and checkout: system shows which item is unavailable and offers to remove it or wait for restock notification

Worked Example 2: Social Media Post Creation

Use Case: User Publishes a Post

*Level: Sea*

*Actor: Authenticated User*

*Preconditions:* User is logged in with a verified account.

*Main Success Scenario:*

  1. User clicks "Create Post" button
  2. System displays post composer with text area and action bar
  3. User types post text (max 500 characters)
  4. User clicks image icon to add a photo
  5. System opens file picker; user selects image
  6. System uploads image, displays preview with remove option
  7. User adds tags by typing # followed by keyword
  8. System autocompletes matching existing tags
  9. User clicks "Publish"
  10. System saves post and makes it visible on the user's profile and followers' feeds
  11. System displays success confirmation and the published post

*Extensions:*

  • 3a. Text exceeds 500 characters: character counter turns red, Publish button disabled
  • 5a. User selects file larger than 10MB: system shows "Image must be under 10MB"
  • 5b. User selects non-image file: system shows "Please select a JPG, PNG, or WebP image"

Key Takeaways

  • The Cockburn fully-dressed template captures all context needed for complex feature development
  • Write use cases at sea level (user goals) — not kite (business strategy) or fish (implementation detail)
  • Include stakeholders and their interests, not just the primary actor
  • Extensions handle all alternate paths — a use case without extensions is probably missing something
  • Special requirements capture non-functional needs: performance targets, security constraints, accessibility

Example

markdown
# Cockburn Fully-Dressed Template

Title:         [Verb phrase — sea level goal]
Scope:         [System name]
Level:         Sea / Kite / Fish
Primary Actor: [Who initiates]

Stakeholders:
  - [Stakeholder]: [Their interest]

Preconditions:
  - [Must be true to start]

Success Guarantee:
  - [True after success]

Main Success Scenario:
  1. [Step]
  2. [Step — actor or system]
  ...

Extensions:
  [step][letter]. [Condition]:
    1. [Response]

Special Requirements:
  - [Performance, security, UX constraints]
Try it yourself — MARKDOWN