Document Use Cases — Requirements Engineering, Part 2

Requirements Engineering · Part 2

"Process a refund" is one line on a ticket and about eleven decisions. What happens past the thirty-day window? What if the payment was part gift card, part card, and the processing fee comes out of somebody's budget? If the use case doesn't decide those, an engineer will — alone, with no authority — and ship the guess.

Part 1 ended with a validated need in the support lead's words: see which refunds will breach the five-day SLA today, ordered by urgency. That isn't buildable until somebody documents what processing a refund involves — every branch, and who owns it. For when this format beats a story, see use cases vs user stories. This is the writing.

Illustrative composite continuing the support-tooling example from Part 1. Figures are illustrative, not measured.

Before You Start

• Prerequisite: a stakeholder interview with a confirmation reply on record — Part 1's output. Without it you're formatting your own assumptions.

• Prerequisite: named access to whoever approves a policy exception — a support lead, and finance for anything moving money.

• Inputs open: the interview write-up, the refund policy (window, reasons, overrides), and one real instance of this going wrong.

What You'll Build

One use case for one interaction — Process a Refund Request: actor and goal, main flow, labelled alternates and exceptions, an extension register, pre/postconditions, frequency, and acceptance criteria. Ninety minutes of work, reviewable in ten.

Step 1: Pick the Interaction and Name the Goal (10 min)

One goal, bounded, end to end: process a refund request — not "refunds," not "the customer clicks Submit."

The decision you'll face: is this a use case at all? The format earns its cost on interactions with multiple branches and multiple actors — "change my display name" has neither.

Check: read the goal aloud to someone outside the team, then name two ways it is reached other than the obvious one. "Handle refunds" fails; "refund eligible lines inside the SLA" passes. If you can't name two, write a story.

Step 2: Write the Main Flow at the Right Altitude (15 min)

Numbered steps, in the agent's language, describing behavior — not implementation.

## Main Flow: Process a Refund Request

1. Agent opens the queue and selects the request nearest its deadline
2. System shows the order, the payment methods used, and the reason
3. Agent confirms the request is inside the 30-day refund window
4. Agent selects the lines to refund
5. System calculates the amount, including tax and shipping
6. Agent approves the refund
7. System submits the refund to the payment provider
8. System closes the request and records the refund on the order
9. System emails the customer a confirmation

Cockburn calls the usable altitude the user-goal level: one actor, one sitting, one complete result. Flow step 3, written badly, twice:

Version	Flow step 3 reads	What's wrong
Too low	"System runs SELECT order_date vs NOW() - 30d"	Design frozen into a requirement.
Too high	"System validates the request"	Against what? Every reader fills the blank differently.
Right	"Agent confirms the request is inside the 30-day window"	Names the actor and the rule, leaves the mechanism open.

Check: point at the actor in every step. A step with no actor — "the request is validated" — hides whose job it is, and that gap gets closed by a guess.

Step 3: Write the Alternates — Where the Feature Hides (15 min)

Alternates still reach the goal. The real requirements surface here, so give this the most time.

A1: Outside the refund window
  At step 3, the order is older than 30 days
   - System shows "outside refund window" with the order date
   - Agent raises an exception; lead approves or declines with a reason

A2: Partial refund
  At step 4, the customer wants only some lines back
   - Only selected lines are refunded; request stays open for the rest

A3: Split-tender order
  At step 5, the order was paid part gift card, part credit card
   - Refund exhausts the gift-card portion first, then the card

A3 arrives as a footnote and turns out to decide who absorbs the card processing fee — which neither engineering nor support can settle. Writing it surfaces that finance owns the answer.

Check: at least one alternate sends you outside your team for a decision. If every branch is answerable at your own desk, you've only written what you already knew.

Step 4: Write the Exceptions (10 min)

Exceptions don't reach the goal. They're what shows up in production logs.

E1: Payment provider rejects the refund
  At step 7 — store credit issued for the same amount, customer
  emailed, item logged for finance review

E2: Confirmation email bounces
  At step 9 — support queue notified, agent makes contact

Check: each exception names what the system does and what a human does next. One that only writes a log line is handled by nobody.

Step 5: Build the Extension Register (10 min)

Prose can't show structure. Five branches written as paragraphs read as five equal footnotes, and nobody can tell which rejoin the flow and which end the story:

Branch	Trigger	What happens	Rejoins at	Who decides
A1	Order older than 30 days	Exception raised; lead rules	step 4 if approved; ends if declined	Support lead
A2	Some lines only	Partial refund, request stays open	step 5	Support agent
A3	Split-tender payment	Gift card drained first, then card	step 8	Finance (fee owner)
E1	Provider rejects refund	Store credit, review item logged	No rejoin — alternate end	Finance
E2	Confirmation bounces	Support queue notified	No rejoin — manual close	Support agent

The rejoin column earns the table: a branch with no rejoin point and no end state is an unfinished flow, and it ships as a customer in limbo.

Check: every row carries a rejoin step or an explicit end state, and an owner who is not "the team." A blank in either column is an open requirement.

Step 6: Preconditions and Postconditions (10 min)

Preconditions are the gate. Postconditions are your test assertions.

## Preconditions
- Agent authenticated with refund permission
- Order in "completed" or "shipped" state
- No refund already in flight against the same lines

## Postconditions (on success)
- Refunded lines show status "Refunded" on the order
- Refund or store credit recorded against the order
- Request removed from the queue with a close reason
- Audit entry written with timestamp, actor, and amounts

Check: cross out any postcondition you couldn't write an assertion for tomorrow. "Customer is satisfied" isn't one; "confirmation email sent" is.

Step 7: Frequency and Acceptance Criteria (15 min)

Frequency lets engineering size the work: a flow that's fine at fifty a day and collapses at two hundred is a different build.

## Frequency
- Typical: ~50 refund requests/day
- Peak: ~200/day in the two weeks after the December holidays
- ~70% currently need an agent to touch them; target under 30%

Then the criteria — observable, each traceable to a flow above. These are acceptance criteria, not a definition of done; the difference is worth settling first.

## Acceptance Criteria
- An in-window, single-tender refund completes with no escalation
- Out-of-window requests route to the support lead, never auto-decline
- A partial refund leaves the request open for the remaining lines
- Split-tender refunds exhaust gift-card balance before the card
- Provider rejections produce store credit and a logged review item
- A bounced confirmation raises a support task, never a silent close
- No request sits unworked past five business days

Criterion four exists only because A3 was written — that's the return on the alternates.

Check: map every row of the register to a criterion. A branch without one is a branch QA never tests and production finds first.

Step 8: Review With the Stakeholder (varies)

Send it to the support lead from Part 1: does the flow match what agents do, are the alternates real, are the exceptions right, what's missing?

Check: they correct at least one thing. Approval without a correction means they skimmed — read the register to them row by row, the part nobody can skim.

You're Done When

• Every register row has a rejoin step or a declared end state, and a named owner.

• Every alternate and exception has an acceptance criterion you could hand to QA unchanged.

• The stakeholder has replied in writing with a correction, and it's in the document.

Those criteria are the raw material for Part 3, where each flow becomes a story that must survive INVEST.

If This Goes Wrong

The main flow runs past fifteen steps. You've merged two use cases. Split where the actor changes: request a refund and reconcile a refund.

Every alternate is answerable by you. You're working from memory, not evidence. Go back to the escalation threads.

Engineering calls it "too vague to build." Usually one step is too high, not all of them. Ask which step they'd guess at, then rewrite that one.

Common Failure Modes

Happy path only. Every branch you skip is a decision handed to whoever hits it first in code.

Branches with no rejoin. Recovery reads like a dead end, and gets built as one.

Sources

• Alistair Cockburn, Writing Effective Use Cases (Addison-Wesley, 2001) — the user-goal ("sea level") altitude and the extension/rejoin structure.

Continue the Requirements Engineering path

• Previous — Part 1: Run Your First Stakeholder Interview

• Next — Part 3: Write User Stories That Pass INVEST

Part of the Requirements Engineering learning path.