What is a specification, and how does it differ from a requirements document?

covers: lo-1

Answer

A specification is the written decision about what must be true — short, one file per capability, written continuously alongside the work, and phrased so that it can be checked.

Pflichtenheft / requirements document specs

written once, before building

written continuously, alongside

prose, hundreds of pages

short, per capability

becomes stale silently

drifts visibly, because the build checks it

"the system should support user management"

a requirement plus scenarios that either hold or do not

The decisive difference is the third row. A classic requirements document is not wrong; it is unverifiable. Nobody can run it, so nothing ever tells you the day it stopped describing the system — it simply becomes fiction quietly, and everybody keeps citing it.

A specification made of requirements and scenarios can be checked, by a person or by a test. When it and the system disagree, somebody finds out, and then there is a decision to take: fix the system, or change the target state deliberately.

Points the answer must contain:

  • Short, per capability, written continuously, checkable

  • The requirements document is written once, is prose, and cannot be verified

  • Drift becomes visible instead of silent

What are Lastenheft and Pflichtenheft, who writes each, and what is in them?

covers: lo-5

Answer
Lastenheft Pflichtenheft

Written by

the client (Auftraggeber)

the contractor (Auftragnehmer)

Answers

what is needed and what for

how and with what it will be realised

Written when

before the tender, before any offer

after the contract is awarded, before building

Serves as

basis for the tender and for comparing offers

basis of the contract and of the acceptance

The sequence is what makes the pair make sense: elicitation → Lastenheft → offer → Pflichtenheft → build → acceptance against the Pflichtenheft. The client states the need in the language of their own world, without prescribing technology; the contractor answers with what will be built, in enough detail that both sides can later agree on whether it was delivered.

Classical In this course

Lastenheft

Ausgangslage and Zielsetzung in the charter — frozen

Pflichtenheft

openspec/specs/ — the living target state

a numbered requirement plus its test case

a requirement with its scenarios, one file per capability

Points the answer must contain:

  • Lastenheft: written by the client, says what is needed and what for, basis for the tender

  • Pflichtenheft: written by the contractor, says how it will be realised, basis of the contract and of the acceptance

  • The sequence: elicitation, Lastenheft, offer, Pflichtenheft, build, acceptance

  • Nothing of it was abolished — the same content lives in charter and specs, in another form

Which chapters does a Pflichtenheft have, and what is the Kriterienkatalog for?

covers: lo-6

Answer

Seven chapters, and their order is an argument rather than a filing system:

  1. Beschreibung der Ausgangslage — who the client is and why they are procuring anything at all

  2. Ist-Zustand — the organisation, the processes and the systems that are already there, limited to what the project touches

  3. Zielsetzung — the goals with priorities, realistic and checkable

  4. Anforderungen (Soll) — at the application software, at the system platform, at the supplier

  5. Mengengerüst — data movements, data volumes, concurrent users

  6. Aufbau und Inhalt der Offerte — only in a tender, so that offers can be compared

  7. Administratives — confidentiality, copyright, distribution list, budget, dates

Chapters 1 to 3 carry the chain initial situation → problem → task: a requirement in chapter 4 that cannot be traced back to them is somebody’s private wish. Chapter 4 itself splits into funktionale requirements — the professional workflow and the data fields — and nichtfunktionale ones: Effizienz, Leistung, Zuverlässigkeit, Robustheit, Benutzerfreundlichkeit, Datenschutz. A non-functional requirement counts as a requirement only once it carries a number or an observable condition.

The catalogue behind that second group is ISO/IEC 25010, the product quality model: nine characteristics — functional suitability, performance efficiency, compatibility, interaction capability, reliability, security, maintainability, flexibility, safety — each with sub-characteristics. Walk the nine when writing chapter 4 and decide per characteristic whether it matters here and what the measurable condition is. "Not applicable" is a valid answer and worth writing down.

The Kriterienkatalog is a different document: internal to the client, written alongside the Pflichtenheft, never handed to the supplier. Its purpose is to evaluate the offers that come in.

  • Muss- or K.-o.-Kriterium — not met, the offer drops out

  • Wunschkriterium (Soll-Kriterium) — the better it is met, the better the rating

  • Abgrenzungskriterium — informative, so the supplier can size the offer

Points the answer must contain:

  • The seven chapters, in order, with Ist-Zustand and Mengengerüst among them

  • Chapter 4 splits into functional and non-functional requirements, with examples of each; ISO/IEC 25010 is the catalogue of the non-functional ones

  • The Kriterienkatalog is a separate, internal document of the client, used to evaluate offers — not a section of the Pflichtenheft

  • Muss-, Wunsch- and Abgrenzungskriterien with their effect on the evaluation

Write a requirement with a scenario for "sessions have a capacity limit"

covers: lo-2

Answer 
## ADDED Requirements

### Requirement: A session cannot be overbooked
The system SHALL refuse a booking when the session has already reached its
capacity.

#### Scenario: Booking a session that is full
- **WHEN** a member books a session whose capacity is 20 and which has 20
  confirmed bookings
- **THEN** the booking is refused and the member is told the session is full

#### Scenario: Booking the last free place
- **WHEN** a member books a session whose capacity is 20 and which has 19
  confirmed bookings
- **THEN** the booking is confirmed

Read it as three parts. The requirement says what must hold, in one sentence, with SHALL. The scenario says how you would observe it: WHEN describes the situation, THEN the outcome, both from outside the system. Together they define what "done" means for this capability.

The second scenario is not decoration. A requirement stated only through its failure case is half-specified — the boundary is exactly where the mistakes live, and "19 of 20" is the case an implementation gets wrong.

Neither part mentions a class, a table or a framework. If you cannot phrase a requirement this way, it is usually not yet understood, or it is a wish.

Points the answer must contain:

  • Requirement with SHALL, stating what must hold

  • Scenario with WHEN and THEN, observable from outside

  • No implementation detail in either

Why did precise statements of intent become the scarce resource?

covers: lo-3

Answer

Because the things around them got cheap.

Cheap now Still expensive

writing the implementation

saying exactly what it must do

producing an explanation of anything

deciding which behaviour is correct here

generating tests that pass

knowing which behaviour must never break

An agent turns a precise description into a working implementation faster than you can type it. It will also produce a plausible implementation from an imprecise description — and that is the actual problem, because the result looks equally finished either way. The gap between "what I said" and "what I meant" used to be absorbed by the slowness of building; now it goes straight into the repository.

So the effort moves to the two ends of the loop: stating the intent precisely enough that a wrong reading is visible, and verifying that what came back matches it. The right-hand column of the table is not cheaper than it was five years ago, and it is now most of the work.

Points the answer must contain:

  • Producing code and explanations is now cheap

  • Deciding which behaviour is correct is not

  • The effort moves to specifying and verifying

What is frozen, what is alive, and why do you need both?

covers: lo-4

Answer

The charter is frozen at approval. The specs are alive and change with every archived change.

q frozen alive
Figure 1. Both, and the difference between them

Each would fail alone. A charter that could be edited is no yardstick: a team adjusts its goals to whatever got finished and every project succeeds by definition. A specification that were frozen would stop describing the system within a fortnight, and then it is a requirements document again — cited, wrong, unrunnable.

Keeping both is what makes the difference readable, and the difference is the content of scope management: what was promised in November, what is true in June, and which archived changes account for the gap. That comparison is the only honest feedback a team gets about its own estimating.

Points the answer must contain:

  • Charter frozen — otherwise there is no yardstick

  • Specs alive — otherwise they stop describing the system

  • The visible difference between them is scope management

Why is "the service uses a repository class" a bad requirement?

covers: lo-1, lo-2

Answer

Because it describes the implementation rather than observable behaviour. Two problems follow, and they are independent of each other.

It cannot be verified from outside. Nobody using the system can tell whether a repository class exists. So the requirement has no scenario — there is no WHEN and THEN that would show it holding or failing — and a requirement nobody can check is not a requirement, it is a preference.

It forbids a better implementation. If it turns out that the query belongs in one place with three lines of SQL, the specification now says no, for a reason nobody would defend if asked. Specifications constrain the outside; the inside is where the team is supposed to be free to improve.

The rewrite asks what the class was supposed to guarantee: "Attendance records SHALL be readable per session and per member" — with a scenario. That keeps whatever the design decision was really for, and leaves the design open. If the repository class genuinely was a decision worth recording, its place is design.md, with the alternative that was rejected.

Points the answer must contain:

  • It describes the implementation, not the observable behaviour

  • It cannot be verified from outside, and it forbids a better implementation