# Step 4: Make quality requirements concrete

## What you get from this step

You end this step with three things:

- A short list of the top quality goals, three or at most five, ranked by priority. They go into section 1.2 of your arc42 documentation.
- A set of quality scenarios. A scenario is a short, concrete description of one situation with a measurable result, so you can decide whether the requirement is met. See [Quality Attribute Scenario](https://arc.fuet.ch/concepts/quality-attributes/quality-attribute-scenario.md).
- A quality tree. It starts with the root "quality", splits into categories, and ends in scenarios. It lives in chapter 10.

Vague wishes like "fast" or "secure" do not help a team decide anything. Scenarios do. See [Insufficient Quality as Driver of Change](https://arc.fuet.ch/concepts/quality-attributes/insufficient-quality-as-driver-of-change.md) for why quality goals shape a system as much as features do.

## What you need first

- A rough picture of what the system does and who cares about it. You need to know which stakeholders have a say.
- A list of the concerns those stakeholders raise, even in loose words such as "must be safe" or "must not go down".
- A shared vocabulary for quality. The [ISO/IEC 25010 Product Quality Model](https://arc.fuet.ch/concepts/quality-attributes/iso-iec-25010-quality-model.md) gives you named characteristics, for example reliability, security and compatibility. Use the 2023 names and see [ISO/IEC 25010:2023 Product Quality Model Revision](https://arc.fuet.ch/concepts/quality-attributes/iso-25010-2023-revision.md) for what changed. For example, Usability is now Interaction Capability.

## If something is missing

- **No list of stakeholder concerns.** Start from the [Standard Quality Attribute List](https://arc.fuet.ch/concepts/quality-attributes/standard-quality-attribute-checklist.md). Walk through it and ask the stakeholders which entries matter. No list is complete, so also ask about qualities it lacks. The [Quality Attribute Coverage in Bass et al.](https://arc.fuet.ch/concepts/quality-attributes/quality-attribute-coverage-in-bass-et-al.md) article shows topics such as deployability and safety that a single list can miss.
- **Stakeholders want everything.** You cannot maximize every quality at once. Rank them by stakeholder importance. See [Quality Attribute Prioritization](https://arc.fuet.ch/concepts/quality-attributes/quality-attribute-prioritization.md) and [Quality Attribute Trade-off](https://arc.fuet.ch/concepts/quality-attributes/architectural-trade-off-thinking.md).
- **Only vague goals exist.** Turn each one into a scenario as described below. If the goal belongs to one use case, start there. See [Quality attributes in use case descriptions](https://arc.fuet.ch/concepts/quality-attributes/quality-attributes-in-use-case-descriptions.md).
- **Decisive stakeholders are not available.** Try to get them into the discussion anyway. The [Utility Tree](https://arc.fuet.ch/concepts/quality-attributes/utility-tree.md) article suggests building the tree together with them.

## How to do it

1. **Collect candidate qualities.** Go through the ISO/IEC 25010 characteristics and a shorter list. Note every quality a stakeholder cares about. Checking two lists keeps topics like compatibility from slipping through.
2. **Tie each candidate to value or risk.** Write down why it matters: business value, a risk, or a key stakeholder's concern. Requirements that are hard to meet, costly to change later, or risky shape the architecture most. See [Architecturally Significant Requirement](https://arc.fuet.ch/concepts/forces-decisions/architecturally-significant-requirement.md).
3. **Rank and cut.** Pick the top three goals, five at most. Put them in a table ordered by priority in section 1.2. See [Quality Attribute Prioritization](https://arc.fuet.ch/concepts/quality-attributes/quality-attribute-prioritization.md).
4. **Write each goal as a scenario.** Use six parts:
   - source: who or what starts it
   - stimulus: the event that happens
   - artifact: the part of the system that is hit
   - environment: the conditions at that moment, such as normal operation or peak load
   - response: what the system does
   - response measure: the number or check that tells you whether the response was good enough

   Use the same form for every scenario. See [Quality Attribute Scenario](https://arc.fuet.ch/concepts/quality-attributes/quality-attribute-scenario.md).
5. **Choose the right scenario type.** A usage scenario describes the runtime reaction to a stimulus. A change scenario describes the effect of modifying or extending the system. See [arc42 Quality Requirements Chapter](https://arc.fuet.ch/concepts/documentation/arc42-quality-chapter.md).
6. **Make every measure checkable.** Examples: a percentile for response time, a percentage over a defined period for availability, or person-weeks for a change. See [Performance Efficiency Scenario](https://arc.fuet.ch/concepts/quality-attributes/performance-scenario.md), [Availability Scenario](https://arc.fuet.ch/concepts/quality-attributes/availability-scenario.md), [Modifiability Scenario](https://arc.fuet.ch/concepts/quality-attributes/modifiability-scenario.md), [Security Scenario](https://arc.fuet.ch/concepts/quality-attributes/security-scenario.md), [Interoperability Scenario](https://arc.fuet.ch/concepts/quality-attributes/interoperability-scenario.md) and [Usability Quality Attribute Scenario](https://arc.fuet.ch/concepts/quality-attributes/usability-scenario.md).
7. **Add lower-priority scenarios.** Keep the total manageable, around ten for most systems. See [Standard Quality Attribute List](https://arc.fuet.ch/concepts/quality-attributes/standard-quality-attribute-checklist.md).
8. **Build the quality tree.** Put "quality" at the root. Add categories below it. Put one or more scenarios at the leaves. A category with no scenarios may be a gap, so review it. See [Utility Tree](https://arc.fuet.ch/concepts/quality-attributes/utility-tree.md).
9. **Place the results in arc42.** Section 1.2 holds the top goals. Chapter 10 references them and adds the lower-priority requirements. See [arc42 Quality Requirements](https://arc.fuet.ch/concepts/documentation/arc42-quality-requirements.md).
10. **Check trade-offs.** For each goal, note which other quality it may hurt. See [Quality Attribute Trade-off](https://arc.fuet.ch/concepts/quality-attributes/architectural-trade-off-thinking.md).

## Example: ClinicBook

ClinicBook is an online booking system for 40 small medical practices. Patients use a website and a mobile app. Practice staff manage calendars. The system must connect to the practices' existing software from different vendors. It sends SMS and e-mail reminders and protects health data. The team is small and the launch date is fixed.

**Step 1–3: candidates and ranking.** The forces point to these candidates: privacy and security, availability in the morning peak, and integration with legacy systems. Performance, ease of change and ease of use also came up. The team keeps three as top goals. The other three go into chapter 10. The numbers below are example values. In a real project, stakeholders must agree on them.

Section 1.2, ordered by priority:

| Priority | Quality goal | Why it matters |
|---|---|---|
| 1 | Security (confidentiality of health data) | Patients trust the service only if their data stays private. |
| 2 | Reliability (availability in the morning peak) | Most bookings and changes happen in the morning. |
| 3 | Compatibility (interoperability with practice software) | A booking that never reaches the practice calendar is useless. |

Related reading: [Confidentiality](https://arc.fuet.ch/concepts/quality-attributes/confidentiality.md), [Availability](https://arc.fuet.ch/concepts/quality-attributes/availability.md), [Interoperability](https://arc.fuet.ch/concepts/quality-attributes/interoperability.md).

**Step 4–6: scenarios for the top goals.**

*S1, confidentiality (usage scenario)*
- Source: a staff member of practice A.
- Stimulus: they try to open the appointments of a patient who belongs to practice B.
- Artifact: the appointment service.
- Environment: normal operation.
- Response: the system denies access and writes an entry to the audit trail.
- Response measure: all 50 test attempts are denied, and each appears in the audit trail within one minute.

*A1, availability (usage scenario)*
- Source: a hardware or software fault.
- Stimulus: one server instance of the booking service crashes.
- Artifact: the booking service.
- Environment: weekday morning peak, 07:30–09:30.
- Response: other instances take over, and patients can keep booking.
- Response measure: no more than 1 minute of failed booking requests. Monthly availability is at least 99.9%, with scheduled maintenance counted as downtime.

Higher availability costs more and adds operating complexity. The team notes this next to A1. It also notes that strict access control (S1) can pull against availability. See [Security](https://arc.fuet.ch/concepts/quality-attributes/security.md).

*I1, interoperability (usage scenario)*
- Source: the ClinicBook booking service.
- Stimulus: a patient books a slot, and ClinicBook sends the booking to the practice's own software.
- Artifact: the integration interface to that software.
- Environment: normal operation. The 40 practice systems are known before runtime.
- Response: if the software accepts the booking, it appears in the practice calendar. If it rejects the booking, ClinicBook tells the patient and notifies practice staff.
- Response measure: 95% of accepted bookings appear in the practice calendar within 30 seconds. Every rejected booking is reported to the patient and to staff within one minute.

Because the integration style is costly to change later, the team looks at it early. See [Architecturally Significant Requirement](https://arc.fuet.ch/concepts/forces-decisions/architecturally-significant-requirement.md) and [Compatibility](https://arc.fuet.ch/concepts/quality-attributes/compatibility.md).

**Step 7: lower-priority scenarios for chapter 10.**

- *P1, performance (usage):* at peak load, 95% of booking page requests finish within 2 seconds. See [Performance Efficiency](https://arc.fuet.ch/concepts/quality-attributes/performance-efficiency.md).
- *M1, modifiability (change):* the team adds support for a new practice-software vendor in at most 3 person-weeks. See [Modifiability](https://arc.fuet.ch/concepts/quality-attributes/modifiability.md).
- *U1, interaction capability (usage):* a first-time patient books an appointment in the app within 3 minutes, without a tutorial. See [Usability](https://arc.fuet.ch/concepts/quality-attributes/usability.md).

**Step 8: the quality tree.**

```
Quality
├─ Security
│  └─ Confidentiality
│     └─ S1: other practice's patient data is denied and logged  [top goal]
├─ Reliability
│  └─ Availability
│     └─ A1: instance crash in morning peak, under 1 min impact  [top goal]
├─ Compatibility
│  └─ Interoperability
│     └─ I1: booking reaches practice software within 30 s       [top goal]
├─ Performance efficiency
│  └─ P1: booking page 95% under 2 s at peak
├─ Maintainability
│  └─ M1: new vendor integration in at most 3 person-weeks
└─ Interaction capability
   └─ U1: first-time booking in 3 minutes without tutorial
```

The team then reviews the branches that have no scenarios. Examples are recoverability and installability. For each, they decide whether it is a real gap or truly not needed. They present the tree to the decisive stakeholders for feedback.

**Step 9: placement.** Section 1.2 holds the table with S1, A1 and I1. Chapter 10 holds the tree, points to the top goals, and lists P1, M1 and U1.

## Done when

- Section 1.2 lists the top three quality goals, five at most, in a table ordered by priority. See [Quality Attribute Prioritization](https://arc.fuet.ch/concepts/quality-attributes/quality-attribute-prioritization.md).
- Every top goal has at least one scenario with source, stimulus, artifact, environment, response and response measure. See [Quality Attribute Scenario](https://arc.fuet.ch/concepts/quality-attributes/quality-attribute-scenario.md).
- Every response measure is specific enough to decide whether the scenario is met. See [arc42 Quality Requirements](https://arc.fuet.ch/concepts/documentation/arc42-quality-requirements.md).
- The quality tree starts at "quality", and its leaves are scenarios, not only category names. See [Utility Tree](https://arc.fuet.ch/concepts/quality-attributes/utility-tree.md).
- Branches without scenarios were reviewed as possible gaps, and decisive stakeholders saw the tree. See [Utility Tree](https://arc.fuet.ch/concepts/quality-attributes/utility-tree.md).
- Chapter 10 references the top goals from section 1.2 and adds lower-priority scenarios, usage and change. See [arc42 Quality Requirements Chapter](https://arc.fuet.ch/concepts/documentation/arc42-quality-chapter.md).
- Each significant goal is linked to business value, risk or a stakeholder concern. See [Architecturally Significant Requirement](https://arc.fuet.ch/concepts/forces-decisions/architecturally-significant-requirement.md).

## Learn more

- [arc42 Quality Requirements](https://arc.fuet.ch/concepts/documentation/arc42-quality-requirements.md)
- [arc42 Quality Requirements Chapter](https://arc.fuet.ch/concepts/documentation/arc42-quality-chapter.md)
- [Quality Attribute](https://arc.fuet.ch/concepts/quality-attributes/quality-attribute.md)
- [Quality Attribute Scenario](https://arc.fuet.ch/concepts/quality-attributes/quality-attribute-scenario.md)
- [Quality Attribute Prioritization](https://arc.fuet.ch/concepts/quality-attributes/quality-attribute-prioritization.md)
- [Quality Attribute Trade-off](https://arc.fuet.ch/concepts/quality-attributes/architectural-trade-off-thinking.md)
- [Utility Tree](https://arc.fuet.ch/concepts/quality-attributes/utility-tree.md)
- [Architecturally Significant Requirement](https://arc.fuet.ch/concepts/forces-decisions/architecturally-significant-requirement.md)
- [ISO/IEC 25010 Product Quality Model](https://arc.fuet.ch/concepts/quality-attributes/iso-iec-25010-quality-model.md)
- [ISO/IEC 25010:2023 Product Quality Model Revision](https://arc.fuet.ch/concepts/quality-attributes/iso-25010-2023-revision.md)
- [Standard Quality Attribute List](https://arc.fuet.ch/concepts/quality-attributes/standard-quality-attribute-checklist.md)
- [Quality Attribute Coverage in Bass et al.](https://arc.fuet.ch/concepts/quality-attributes/quality-attribute-coverage-in-bass-et-al.md)
- [Quality attributes in use case descriptions](https://arc.fuet.ch/concepts/quality-attributes/quality-attributes-in-use-case-descriptions.md)
- [Insufficient Quality as Driver of Change](https://arc.fuet.ch/concepts/quality-attributes/insufficient-quality-as-driver-of-change.md)
- Scenario templates: [Security Scenario](https://arc.fuet.ch/concepts/quality-attributes/security-scenario.md), [Availability Scenario](https://arc.fuet.ch/concepts/quality-attributes/availability-scenario.md), [Interoperability Scenario](https://arc.fuet.ch/concepts/quality-attributes/interoperability-scenario.md), [Performance Efficiency Scenario](https://arc.fuet.ch/concepts/quality-attributes/performance-scenario.md), [Modifiability Scenario](https://arc.fuet.ch/concepts/quality-attributes/modifiability-scenario.md), [Usability Quality Attribute Scenario](https://arc.fuet.ch/concepts/quality-attributes/usability-scenario.md)