Sort the sentences into the right artefact

kind: drill

Each sentence comes from a real student change. Say where it belongs — proposal.md, the spec delta, design.md, tasks.md — or that it belongs nowhere.

  1. "Trainers currently write attendance on paper and lose the sheets."

  2. "The system SHALL record attendance per member and session."

  3. "We chose PostgreSQL over SQLite because two trainers enter data at the same time."

  4. "Create the Attendance entity."

  5. "This will be really useful for the club."

  6. "GIVEN a session that has already ended, WHEN a trainer records attendance, THEN the entry is refused."

  7. "Marco does the frontend, Lisa the backend."

Solution

  1. Proposal — the why, stated in the client’s terms rather than the team’s.

  2. Spec delta — a requirement: what must be true afterwards.

  3. Design — a decision with a rejected alternative and a reason. Note that the reason is a fact about the client (concurrent writers), not a preference.

  4. Tasks — but not yet usable: it names no verification. "Create the Attendance entity; ./gradlew test compiles and AttendanceTest passes."

  5. Nowhere. Not checkable, not action-changing, and it is the kind of sentence that makes a proposal unreviewable.

  6. Spec delta — a scenario, and a refusal one, which is the kind teams forget.

  7. Nowhere in the change. Who does what is team organisation. It changes weekly and would be wrong in the archive within a fortnight.

Sentences 5 and 7 are the interesting ones: both feel like they belong somewhere, and neither survives the question "would this still be true, and still matter, in a year?"

Repair a specification

kind: drill

A team wrote this. Find the defects and rewrite it.

### Requirement: Booking

The BookingController should have a POST /bookings endpoint that inserts a row
into the bookings table and returns 200. It should be fast.

#### Scenario: booking works
- GIVEN the app is running
- WHEN I book
- THEN it works
Solution

Four defects.

  • Implementation instead of behaviour. Controller, endpoint, table and status code are design. The first rename makes the spec wrong although nothing about the requirement changed.

  • "should" instead of SHALL. A requirement is binding or it is not a requirement.

  • "It should be fast." Not observable. Either give a number or drop it.

  • The scenario checks nothing. "I book" and "it works" name no values and no observable result — it cannot fail, so it cannot pass.

Rewritten:

### Requirement: A member can book a place in a session

The system SHALL record a booking for a member in a session that has free
capacity, and SHALL confirm it to the caller within 2 seconds.

#### Scenario: booking a free place
- **GIVEN** a session with capacity 20 and 3 confirmed bookings
- **WHEN** member M books that session
- **THEN** the booking is recorded as confirmed
- **AND** the confirmation names the session and the member

#### Scenario: booking a session that already started
- **GIVEN** a session whose start time is in the past
- **WHEN** member M books that session
- **THEN** the booking is refused
- **AND** the response names the reason "session already started"

The refusal scenario was not in the original at all. It usually is not — and it is the one that turns out to matter.

Decide: design document or not

kind: drill

For each change, say whether it needs a design.md, in one sentence.

  1. Add a notes field to the member form.

  2. Store uploaded photos: in the database or on the file system?

  3. Rename SessionSvc to SessionService.

  4. Introduce a scheduling library instead of writing the recurrence rules.

  5. Fix a sorting bug that shows sessions in the wrong order.

  6. Decide not to build the statistics page that the charter mentions.

Solution

  1. No. One sensible implementation, no choice made.

  2. Yes. Two real options with different consequences for backup and size.

  3. No. Nothing was decided that anybody would ask about later.

  4. Yes. A new dependency is a decision — it has to be maintained, updated and understood by four people.

  5. No. There is one correct behaviour; the bug is not a choice.

  6. Yes, and this is the one teams miss. A deliberate omission is a decision, and the only place it can be recorded is a design document — otherwise the June question "why is this missing?" has no answer except "we forgot".

The pattern: the trigger is a choice, and choices include the choice not to do something.

Write the artefacts for one change in your project

kind: project

Pick one intention from your project that is genuinely reviewable in one sitting. Then:

  1. Write proposal.md. Three paragraphs: why now (in the client’s words), what changes, which capabilities are touched. Delete every sentence starting with "we will" and check whether a reason is left.

  2. Write the spec delta. At least one requirement with SHALL, and three scenarios: normal case, boundary, refusal.

  3. Decide whether design.md is needed and write down the answer either way — including "no decision was taken here" if that is the case.

  4. Write tasks.md so that every entry names how it is verified, in an order that reflects what depends on what.

  5. Run openspec validate --changes and have another team member review the spec with one question only: what would prove this wrong?

If they cannot answer that question for a scenario, the scenario is not finished.