Quality Attribute Scenarios
Overview
Section titled “Overview”You now have a short list of requirements that will shape the structure. Most of them are currently written as adjectives — fast, accurate, reliable, cheap — and an adjective cannot be satisfied or violated.
This topic is the fix: a fixed six-part form that forces every missing detail into the open.
Why adjectives fail
Section titled “Why adjectives fail”“The system should be fast” survives every review because nobody can disagree with it. That is precisely the problem. It passes without ever being tested, and then six months later two people discover they meant different things by it.
An untestable requirement fails in three specific ways. It cannot be verified, so nobody knows whether the architecture satisfies it. It cannot be traded off, because you cannot compare two options against an adjective. And it cannot be refused — you have no grounds to say “no, that costs more than the driver is worth” when you do not know what that is.
The six parts
Section titled “The six parts”A quality attribute scenario is a requirement written in six named parts. The form comes from the Software Engineering Institute’s work on architecture evaluation — Bass, Clements and Kazman set it out in Software Architecture in Practice — and it is the most reusable thing in it.
graph TD S["<b>Source</b><br/>who or what<br/>triggers it"] --> ST["<b>Stimulus</b><br/>the event<br/>that arrives"] ST --> A["<b>Artifact</b><br/>the part of the<br/>system affected"] A --> E["<b>Environment</b><br/>the state the system<br/>is in at the time"] E --> R["<b>Response</b><br/>what the system<br/>must do"] R --> RM["<b>Response measure</b><br/>the number that<br/>decides pass or fail"] classDef plain fill:#5B8FB9,stroke:#4A7A9E,stroke-width:2px,color:#ffffff classDef omitted fill:#E8A33D,stroke:#C4832A,stroke-width:2px,color:#ffffff class S,ST,A,R plain class E,RM omitted
The six parts in order. The two amber ones are the parts people leave out — and they are the two that decide whether the scenario is worth writing.
Source — who or what initiates the event. A customer, an internal user, a scheduled job, another system, an attacker.
Stimulus — the event itself, stated concretely. Not “load increases” but “concurrent conversations rise to four times the daily median”.
Artifact — which part of the system is on the hook. The whole system, the retrieval path, the action layer, the embedding pipeline. Naming it narrows where the architecture has to respond.
Environment — the state the system is in when the stimulus arrives. Normal operation, peak load, a dependency degraded, a model provider unavailable, mid-deployment. This is the part that gets skipped, and skipping it quietly means “normal operation only”, which is the one case that was never going to be the problem.
Response — what the system must do. Observable behaviour, not internal mechanism.
Response measure — the number that decides pass or fail. A threshold, a percentile, a rate, a ceiling.
Writing the response measure
Section titled “Writing the response measure”This is where most scenarios collapse back into adjectives, so three rules:
Use a percentile, not an average. An average response time hides the tail, and the tail is what users experience and remember. Averages also make two very different systems look identical.
State the measurement window. “99.9% availability” over a day, a month and a quarter are three different requirements with wildly different costs.
Pick a number you could lose. If no realistic design would fail the measure, you have written a description rather than a requirement. A good threshold is one that at least one plausible option fails.
When environment does the work
Section titled “When environment does the work”A worked example of why the skipped part matters.
“The assistant responds within four seconds” sounds complete. Add environments and it becomes three separate requirements: within four seconds in normal operation; within four seconds when the primary model provider is timing out; within four seconds while the embedding pipeline is running its weekly refresh.
The first is a performance requirement. The second is an availability requirement wearing a performance costume, and it forces a fallback path. The third is a resource-contention question that forces a decision about isolation. One sentence, three structures — and only the environment column reveals that.
What this costs
Section titled “What this costs”Scenarios are tedious to write, and a full set for a real system is a document nobody will read end to end.
So do not write a full set. Write scenarios only for the ASRs. Six to twelve scenarios for a significant initiative is a healthy number; forty means you have started documenting functions, and the set will go stale before anyone uses it.
The other cost is political. A specific number invites argument, where an adjective invited none. That argument is the point — it is the cheapest it will ever be to have.
Feeds the workbook
Section titled “Feeds the workbook”Every ASR on your list needs a scenario. Make sure the environments vary: if all six of yours say “normal operation”, you have specified the easy case and nothing else.
→ You can write them. You cannot afford to satisfy all of them equally — so which come first? — The Utility Tree