Lab-05: Requirement Engineering

1. Tools. Git, the GitHub CLI gh (for task 5; the web interface works too), a Markdown editor with Mermaid preview (VS Code with the extension Markdown Preview Mermaid Support, or mermaid.live), and a spreadsheet (LibreOffice Calc or Excel) for the CSV files. No compiler is needed this week; if your repository already contains code, it must still build.

   git --version
   gh --version            # GitHub CLI 2.x
   gh auth status          # must show your GitHub account
   # work in the team repository created in Lab-01
   cd clubhub
   git switch main && git pull
   git switch -c lab-05
   mkdir -p lab05

2. The two-week plan. Book the 20-minute interview slot with the instructor or teaching assistant (the client) at the start of week 5; the client will also be available for 5 minutes at the end of the week-5 lab and for the MoSCoW decision in week 6.

   flowchart TB
     subgraph W5[Week 5: elicitation and analysis]
       direction LR
       T1[Task 1: interview and raw needs] --> T2[Task 2: classify and resolve conflicts]
     end
     subgraph W6[Week 6: specification and management]
       direction LR
       T3[Task 3: stories and use case] --> T4[Task 4: SRS and peer review]
       T4 --> T5[Task 5: backlog, matrix, issues]
     end
     W5 --> W6
     W6 -.-> C[Challenge: prototype validation]
   

3. Inputs from earlier labs. This lab reuses four earlier deliverables. If one is incomplete, use the fallback in the table and say so in lab05/README.md; do not stop to repair the earlier lab.

   Input	Where	What you need from it	Fallback if missing
   Problem statement and stakeholders	lab01/ (Lab-01)	The problem in one paragraph; the stakeholder list, to choose whom the client should play and to check nobody is forgotten	Problem: club events are announced on social media and signed up on paper, so rooms overflow and nobody knows who attended. Stakeholders: the roles in the case-study brief below.
   Quality attribute scenarios	lab02/ (Lab-02)	Each scenario (source, stimulus, environment, response, measure) becomes one NFR in task 4	(1) 100 students check in within 10 min; 95 % confirmed within 1 s. (2) A first-time student registers in under 60 s. (3) After a crash during saving, no registration is lost.
   Data inventory	lab03/ (Lab-03)	Personal data fields, purpose, who may see them, retention: source of the privacy requirements	Student ID, name, email (needed); phone (optional); attendance records kept until the end of the academic year; organisers see only their own events' attendees.
   Process and iteration plan	lab04/ (Lab-04)	Sprint dates and length, to place the Must stories in Sprint 1	Sprint 1 weeks 9-10, Sprint 2 weeks 11-12, demo in week 14, about 15 story points per sprint for a team of five.

4. Case-study brief. The box below holds every case-study fact this lab needs. Wherever a step says "the case-study brief", it means this box. Treat it as your starting knowledge; the interview in task 1 will add details and may contradict it (then the client's answer wins, recorded as a decision).
   Case-study brief: ITC Club Hub

   Purpose

   An application for the student clubs of the Institute of Technology of Cambodia. Teams analyse and model the full system as a web and mobile application and implement its core in C++20: domain model, business rules and a command-line front end with CSV or JSON file storage.

   Roles

   Student: browses events, registers, cancels, receives a reminder. Club leader (usually the club president): registers the club, publishes events. Organiser: checks registered students in at the door and sees attendance. Administrator (Student Affairs Office): approves or rejects clubs, sees a monthly activity report across clubs.

   Features

   Club registration and approval · events with title, date and time, location, capacity and description · browse and register · cancel up to 24 hours before the start · reminder · check-in at the door · attendance per event · monthly activity report. The waiting list for full events is a Should feature.

   Business rules

   Capacity cannot be exceeded · a student cannot register twice for the same event · cancellation closes 24 hours before the start · events in the past cannot be registered for · only approved clubs can publish events.

   Personal data

   Student ID, name, email, phone (optional), club membership, attendance records.

   Domain names

   Club, Event, Student, Registration, ClubStatus (Pending, Approved, Rejected), RegistrationStatus (Registered, Cancelled, CheckedIn, Waitlisted), RegistrationService with registerStudent, cancel, checkIn. Use these words in requirements and test names so that Lab-06 and the code match.

   The client

   The instructor or a teaching assistant plays the client and can answer as a club president, an organiser, an administrator or a student. Your Product Owner is the team's single contact and brings decisions back to the team.

   Project rhythm

   15-week semester · midterm in week 8 (project checkpoint 1: requirements and models reviewed) · Sprint 1 in weeks 9-10 · Sprint 2 in weeks 11-12 · project submission and demo in week 14.

5. Deliverable folder. Create these files in lab05/ as you go.

   clubhub/
   ├── lab01/ lab02/ lab03/ lab04/       # earlier labs, read-only here
   └── lab05/
       ├── interview-script.md           # Task 1 (week 5)
       ├── interview-notes.md            # Task 1
       ├── raw-needs.csv                 # Task 1
       ├── requirements.md               # Task 2 (week 5)
       ├── conflicts.md                  # Task 2
       ├── user-stories.md               # Task 3 (week 6)
       ├── use-case-register.md          # Task 3
       ├── srs.md                        # Task 4
       ├── srs-review.md                 # Task 4 (your review of the partner SRS)
       ├── backlog.csv                   # Task 5
       ├── traceability.csv              # Task 5
       ├── README.md                     # Task 5 (record what changed)
       ├── prototype/                    # Challenge
       ├── prototype-validation.md       # Challenge
       └── change-requests/CR-001.md     # Challenge

6. Conventions. Ids are stable and never reused: raw needs N-01, user requirements UR-01, system requirements FR-01 and NFR-01, stories US-01, use cases UC-01, change requests CR-001. Every Markdown file starts with a title, a version and a date. Commit after each task with a message starting Lab-05 task N:.

Goal

Prepare a script, run a 20-minute interview with the client, and turn the notes into a list of at least 15 raw needs written in the stakeholder's own words. Lead: the Product Owner runs the interview; every member prepares and asks questions.

Steps

1. Re-read your Lab-01 stakeholder list and the case-study brief. Choose the two roles you want the client to play (at least one of club president or organiser) and write three interview goals at the top of lab05/interview-script.md (for example "understand check-in at the door").
2. Write the script from the starter: five sections (opening, context, needs, probing, wrap-up) and 10 to 14 questions. Include at least two questions on quality (speed, devices, what happens when the Wi-Fi fails), one on personal data, and one on what goes wrong today. Start open ("Tell me about the last event...") and avoid leading questions. Each member adds at least two questions in their own commit.
3. Assign roles: interviewer (Product Owner), note-taker, time-keeper; the others ask their own questions when the interviewer hands over. Book the 20-minute slot with the client.
4. Run the interview. The note-taker writes lab05/interview-notes.md: date, who asked and who noted, then one block per question number with the client's words in quotes. Whenever the client uses an adjective ("quick", "many", "soon"), ask for a number and note it.
5. Within 24 hours, extract the raw needs into lab05/raw-needs.csv with the columns id,stakeholder,need,source,type_guess,notes: one need per row, at least 15 rows, source is the question number (Q4) or Brief, type_guess is F or NF. Mark obvious conflicts in notes.
6. End the notes with a section Open questions; send them to the client (team channel or a GitHub issue labelled question) and record the answers under each question.
7. Commit as Lab-05 task 1: elicitation interview and push.

Starter

# Interview script · ITC Club Hub
Version 0.1 · 2026-10-05 · Team <name>
Client role(s): club president, organiser
Goals: 1. ...  2. ...  3. ...
Interviewer: <PO> · Notes: <name> · Time: <name>

## Opening (2 min)
- Thank the client, explain the purpose, ask permission to take notes

## Context (5 min)
1. Walk me through the last event your club organised.
2. ...

## Needs (8 min)
3. ...

## Probing (3 min)
- "You said *quick*: how many seconds is quick?"

## Wrap-up (2 min)
- What should we have asked but did not?
- Summarise the top three needs; agree how to send follow-up questions

id,stakeholder,need,source,type_guess,notes

Expected output (excerpt of raw-needs.csv)

id,stakeholder,need,source,type_guess,notes
N-01,Student,"See the events of all clubs in one place",Q2,F,
N-03,Organiser,"Check-in is scan, beep, next: about a second",Q7,NF,number asked in Q7
N-04,Organiser,"Check-in keeps working when the hall Wi-Fi drops",Q5,NF,
N-08,Organiser,"Phone number of every student to call no-shows",Q6,F,conflicts with lab03 data inventory
N-12,President,"Know how many registered students really came",Q9,F,
...

Show hints

Acceptance checklist

Goal

Turn the raw needs into user requirements and refine them into functional and non-functional system requirements, then resolve three given conflicts between stakeholders and have the client confirm the decisions. Lead: the whole team classifies; the Product Owner takes the conflict decisions to the client.

Steps

1. Create lab05/requirements.md from the starter. For each raw need write one user requirement UR-xx in plain language, with its source need ids and a type (F or NF). Merge duplicates (one UR may cite several needs).
2. Move needs that are out of scope for release 1 (payments, chat, room booking...) to a table Rejected or deferred needs with a one-line reason. Nothing is silently dropped.
3. Refine each user requirement into one or more system requirements: FR-xx "The system shall ..." for behaviour, NFR-xx with its ISO/IEC 25010 category (performance efficiency, interaction capability, reliability, security, compatibility, maintainability, flexibility) for qualities. Aim for at least 12 FRs and 5 NFRs; every business rule of the case-study brief must appear as an FR.
4. Add one NFR per Lab-02 quality attribute scenario (keep its measure) and one privacy requirement per personal data field of the Lab-03 data inventory (who may see it, how long it is kept). Mark their source as Lab-02 S1 or Lab-03 phone.
5. Resolve the three conflicts below in lab05/conflicts.md using the template: stakeholders and their positions, the interest behind each position, at least two options, the decision, the rationale, and the requirement ids you created or changed.

   Id	Position A	Position B
   C1	Organiser: "Make the phone number mandatory, we must be able to call no-shows."	Student representative (and your Lab-03 data inventory): "The phone number stays optional; collect only what is needed."
   C2	Club president: "Let students cancel until the event starts; flexibility attracts people."	Organiser: "Close cancellation 48 hours before; we order food and print badges two days ahead."
   C3	Administrator: "I want to approve every event before it becomes visible."	Club leaders: "We must be able to publish on the same day; approval takes a week."

6. At the end of the week-5 lab, the Product Owner presents the three decisions to the client (5 minutes). Record Agreed by and the date under each conflict, or the client's counter-decision; update the affected requirements.
7. Commit as Lab-05 task 2: classified requirements and conflicts.

Starter

# Requirements (classified) · ITC Club Hub
Version 0.1 · 2026-10-07 · Team <name>

## User requirements
| UR | Statement | Needs | Type |
|----|-----------|-------|------|
| UR-01 | A student can see the events of all clubs. | N-01 | F |

## System requirements
| Id | Requirement | Refines | Category |
|----|-------------|---------|----------|
| FR-01 | The system shall ... | UR-.. | - |
| NFR-01 | ... within 1 s for 95 % of ... | UR-.. | Performance efficiency |

## Rejected or deferred needs
| Need | Reason |
|------|--------|

# Conflicts · ITC Club Hub
## C1 · Phone number: mandatory or optional
- Positions: Organiser ... / Student representative ...
- Interests: ...
- Options: (a) ... (b) ... (c) ...
- Decision: ...
- Rationale: ...
- Requirements created or changed: ...
- Agreed by: <client>, <date>

Expected output (excerpts; the conflict shown is the overbooking example from the slides, not one of C1 to C3)

| UR-04 | A student can cancel a registration. | N-05, N-11 | F |

| FR-06 | The system shall reject a cancellation made less than 24 hours before the event start. | UR-04 | - |
| FR-07 | On a valid cancellation the system shall set the Registration to Cancelled and free one place. | UR-04 | - |
| NFR-02 | 4 of 5 first-time students register for an event in under 60 s without help. | UR-02 | Interaction capability |

## C0 · Overbooking
- Positions: President "accept 10 % more than the seats" /
  Administrator "the room limit is a safety rule"
- Interests: full rooms / safety
- Options: (a) overbook 10 % (b) hard limit (c) hard limit + waiting list
- Decision: (c); capacity is a hard limit (FR-03), waiting list FR-12 (Should)
- Agreed by: client (as administrator), 2026-10-09

Show hints

Acceptance checklist

Goal

Write 15 to 20 user stories with Given/When/Then acceptance criteria that cover every role and every Must feature, check three of them with INVEST, and write one complete textual use case with its main and alternative flows. Lead: the developers write the stories; the Product Owner reviews them in the pull request.

Steps

1. In lab05/user-stories.md, list the stories in the order a user meets them (club registration, publishing, browsing, registering, cancelling, reminder, check-in, attendance, report). Number them US-01..; aim for 15 to 20. Every role of the brief appears at least twice.
2. Write each story with the card (As a role, I want capability, so that benefit) and the fields Priority (TBD until task 5), Source (FR ids from task 2) and Size (TBD).
3. Add at least two Gherkin scenarios per story: the happy path and one error or boundary case. Every Then names an observable result (a status, a message, a number). Each of the five business rules appears as a scenario, and the 24-hour rule is tested on both sides of the boundary.
4. Add an INVEST check table for three stories (one row per letter, one sentence each). Split any story you would size above 8 story points.
5. In lab05/use-case-register.md, write UC-02 Register for an event with the template: primary actor, stakeholders and interests, precondition, trigger, main success scenario (5 to 9 numbered steps), at least three alternative flows numbered after their step (event in the past, already registered, event full), and the postcondition. Add a Mermaid flowchart of the main and alternative flows below it.
6. Each member writes at least three stories in their own commits; the Product Owner comments on at least three stories in the pull request and the authors fix them.
7. Commit as Lab-05 task 3: user stories and use case.

Starter

### US-03 · Register a club
**As a** club leader **I want** to register my club
**so that** it can publish events once it is approved.
Priority: TBD · Source: FR-10 · Size: TBD

```gherkin
Scenario: New club is pending
  Given no club named "Robotics Club" exists
  When I register "Robotics Club" with a description and my student ID
  Then the club status is Pending
  And the administrator sees it in the list of clubs to approve

Scenario: Duplicate club name
  Given a club named "Robotics Club" exists
  When I register "Robotics Club"
  Then the registration is rejected with "Club name already used"
```

# UC-02 · Register for an event
Primary actor: Student · Level: user goal
Stakeholders and interests: ...
Precondition: ...
Trigger: ...
## Main success scenario
1. ...
## Alternative flows
2a. The event is in the past: ...
## Postcondition
...
```mermaid
flowchart TD
  A([Student selects Register]) --> B{Event in the future?}
```

Expected output (INVEST check for one story)

Show hints

Acceptance checklist

Goal

Write a short software requirements specification lab05/srs.md following the 29148-based template, with measurable NFRs derived from your Lab-02 scenarios and privacy requirements from your Lab-03 data inventory; then review a partner team's SRS with the quality checklist and baseline your own as version 1.0. Lead: the Product Owner owns srs.md; each member writes one section in their own commit.

Steps

1. Create lab05/srs.md from the starter template and fill the version table.
2. Section 1: purpose (who reads it), scope with an explicit out of scope list, product overview (users, main functions, limitations) and at least 8 definitions (Club, Event, Registration, Check-in, Waiting list, Organiser, ...).
3. Section 3.2: every FR from task 2 as "The system shall ...", one statement per id, each with Priority, Source and Verification (test, demonstration, inspection or analysis). Correct any weak words (fast, easy, user-friendly, etc.) on the way.
4. Sections 3.3 to 3.7: the NFRs, at least one per Lab-02 scenario with its measure and load condition; at least three privacy requirements from Lab-03 (which fields, who sees them, retention and deletion); the design constraints (C++20, CMake, file storage in CSV or JSON, command-line interface).
5. Section 4: a verification method for every requirement id (a table is fine). Section 5: assumptions and a glossary.
6. Exchange SRS files with the partner team named by the teaching assistant. Review theirs with the checklist in the starter and record at least 8 findings in lab05/srs-review.md (id, location, characteristic violated, finding, suggestion, severity). Send the review to them as a GitHub issue in their repository.
7. Fix the findings you received (or reply why not), add the row "1.0 · baseline after peer review" to your version table, commit as Lab-05 task 4: SRS baseline and tag it: git tag srs-v1.0.

Starter (lab05/srs.md template)

# ITC Club Hub · Software Requirements Specification
Structure adapted from ISO/IEC/IEEE 29148:2018

| Version | Date | Author | Change |
|---------|------|--------|--------|
| 0.1 | 2026-10-12 | <name> | First draft from requirements.md |

## 1 Introduction
### 1.1 Purpose
### 1.2 Scope              (in scope / out of scope)
### 1.3 Product overview   (users, main functions, limitations)
### 1.4 Definitions        (at least 8 terms)
## 2 References            (lab01 to lab04 files, ISO/IEC/IEEE 29148:2018)
## 3 Specific requirements
### 3.1 External interfaces   (CLI commands, CSV or JSON files)
### 3.2 Functions
- FR-01 The system shall ...
  Priority: Must · Source: N-.., UR-.. · Verification: test
### 3.3 Usability (interaction capability)
### 3.4 Performance
### 3.5 Reliability
### 3.6 Security and privacy   (from the lab03 data inventory)
### 3.7 Design constraints
## 4 Verification             (method per requirement id)
## 5 Appendices
### 5.1 Assumptions and dependencies
### 5.2 Glossary

# SRS review checklist (copy into srs-review.md)
| # | Check | Yes/No | Findings |
|---|-------|--------|----------|
| 1 | Every requirement has a unique id and a source | | |
| 2 | Unambiguous: no weak words (fast, easy, user-friendly, etc.) | | |
| 3 | Singular: one "shall" per requirement | | |
| 4 | Testable: a test or inspection can pass or fail | | |
| 5 | Complete: errors and boundaries (full, past, 24 h) covered | | |
| 6 | Consistent: no two requirements contradict | | |
| 7 | Feasible: buildable in C++20 with a CLI in two sprints | | |
| 8 | Every NFR has a measure and a load or condition | | |
| 9 | Each personal data field has visibility and retention | | |
| 10 | Scope lists what is out of scope | | |

Expected output (excerpt of srs-review.md)

Show hints

Acceptance checklist

Goal

Estimate and prioritise the stories into lab05/backlog.csv with MoSCoW and story points, start the traceability matrix lab05/traceability.csv, create one GitHub issue per Must story, and record the lab in lab05/README.md. Lead: the Product Owner runs the MoSCoW session with the client; the whole team estimates.

Steps

1. Estimate. Size every story with planning poker using 1, 2, 3, 5, 8, 13 (everybody reveals at once; the highest and lowest explain, then vote again). Split any story above 8 and update user-stories.md.
2. Prioritise. With the client, assign Must, Should, Could or Won't and a value from 1 to 5. Write lab05/backlog.csv with the columns id,title,role,moscow,points,value,sprint,fr_ids,issue, ordered by MoSCoW then by value. Check that Must stories take at most 60 % of the Must + Should + Could points (script in the Submission section); if not, renegotiate.
3. Value vs effort. Draw a Mermaid quadrantChart of the Must and Should stories in README.md (x: points relative to the largest story, y: value / 5). Use it to order the Must stories for Sprint 1 (sprint column).
4. Traceability. Create lab05/traceability.csv with req_id,source,story_ids,design_element,test_name,status: one row per FR and NFR of srs.md. design_element is TBD (Lab-06); test_name is a future GoogleTest name in the form Class_Behaviour (for example RegistrationService_RejectsWhenEventFull). Mark rows without a story or a test name as gap and list the gaps in the README.
5. Issues. Create the labels story and must, then one issue per Must story, titled US-xx Title, with the card and the scenarios in the body. Put the issue number in the issue column of backlog.csv.
6. Record what changed. Create lab05/README.md with: a table of every Lab-05 file with a one-line description; a table Inputs reused naming the lab01/ to lab04/ files you used with their version, tag or commit hash (or "fallback from the Setup table"); the Must share calculation; the quadrant chart; the list of traceability gaps; and a change-log row (date, version, what changed, who).
7. Commit as Lab-05 task 5: backlog, traceability and issues, push the branch and open the pull request (see Submission).

Starter

# lab05/backlog.csv
id,title,role,moscow,points,value,sprint,fr_ids,issue
US-02,Register for an event,Student,Must,5,5,1,FR-03 FR-04 FR-05,#7

# lab05/traceability.csv
req_id,source,story_ids,design_element,test_name,status
FR-03,N-02,US-02,TBD (Lab-06),RegistrationService_RejectsWhenEventFull,planned

# labels (once per repository)
gh label create story --color 1D76DB --description "User story"
gh label create must  --color B60205 --description "MoSCoW: Must"

# one issue per Must story; the body is the story's section of user-stories.md
gh issue create --title "US-02 Register for an event" --label story,must \
  --body "$(awk '/^### US-02/{p=1;next} /^### /{p=0} p' lab05/user-stories.md)"

gh issue list --label must      # one issue per Must story?

# Lab-05 · Requirement Engineering
Version 1.0 · 2026-10-16 · Team <name>

## Files
| File | Content |
|------|---------|
| interview-script.md | Script of the 20-minute client interview |
| ... | ... |

## Inputs reused
| Input | File | Version, tag or commit |
|-------|------|------------------------|
| Stakeholders | lab01/... | ... |

## Backlog
Must share: .. SP / .. SP = .. % (limit 60 %)

## Traceability gaps
- ...

## Change log
| Date | Version | What changed | Who |
|------|---------|--------------|-----|

Expected output (quadrant chart in README.md, rendered; your stories and positions will differ)

quadrantChart
  title Must and Should stories: value vs effort
  x-axis Low effort --> High effort
  y-axis Low value --> High value
  quadrant-1 Plan carefully
  quadrant-2 Do first
  quadrant-3 Fill in later
  quadrant-4 Defer
  US-01 Browse: [0.2, 0.7]
  US-02 Register: [0.38, 0.96]
  US-06 Approve club: [0.15, 0.6]
  US-07 Check-in: [0.42, 0.84]
  US-09 Waiting list: [0.62, 0.6]
  US-11 Report: [0.38, 0.4]

Show hints

Acceptance checklist

1. Repository layout:

   clubhub/
   ├── README.md
   ├── lab01/  lab02/  lab03/  lab04/
   └── lab05/
       ├── interview-script.md   interview-notes.md   raw-needs.csv
       ├── requirements.md       conflicts.md
       ├── user-stories.md       use-case-register.md
       ├── srs.md                srs-review.md
       ├── backlog.csv           traceability.csv
       ├── README.md
       └── prototype/  prototype-validation.md  change-requests/   # challenge

2. Self-check from a clean checkout (it prints counts you can compare with the checklists):

   grep -c '^### US-' lab05/user-stories.md     # 15..20 stories
   grep -c 'Scenario:' lab05/user-stories.md    # at least 2 per story
   grep -inE '\b(fast|easy|user-friendly|flexible|etc)\b' lab05/srs.md
   git tag --list 'srs-v*'                      # srs-v1.0 (and srs-v1.1)
   gh issue list --label must --state all       # one per Must story
   python - <<'EOF'
   import csv, re
   rows = list(csv.DictReader(open("lab05/backlog.csv", encoding="utf-8")))
   pts = lambda m: sum(int(r["points"]) for r in rows if r["moscow"] == m)
   total = sum(pts(m) for m in ("Must", "Should", "Could"))
   print(f"Must share: {pts('Must')} / {total} = {pts('Must') / total:.0%}")
   srs = open("lab05/srs.md", encoding="utf-8").read()
   ids = set(re.findall(r"\b(?:FR|NFR)-\d+\b", srs))
   trace = csv.DictReader(open("lab05/traceability.csv", encoding="utf-8"))
   missing = ids - {r["req_id"] for r in trace}
   print("SRS ids:", len(ids), "missing in matrix:", sorted(missing) or "none")
   EOF

   If your repository already contains C++ code from earlier labs, it must still build: cmake -S . -B build && cmake --build build && ctest --test-dir build. No code changes are expected in this lab.
3. Branch lab-05 with the tags srs-v1.0 (and srs-v1.1 for the challenge) pushed (git push --tags); pull request titled Lab-05 – <team name>, reviewed by at least one other team member before the deadline of week 6.