Requirements: Elicitation, Specification, and GitLab

SENG 365 — Software Engineering

Neil Ernst

nernst@uvic.ca

University of Victoria

2026-09-09

Learning Objectives

Elicit, deconstruct, and refine functional requirements and quality attributes
Describe requirements succinctly, completely, and precisely
Write and evaluate user stories and acceptance criteria
Build a domain model or glossary from a problem statement
Use GitLab issues, labels, and boards to elicit and track requirements — then extract them into docs/a1-requirements.md
Understand enough of both model problems to choose one and start A1

Why Requirements First

Requirements Come Before Design

What matters is who the system is for and what they need. They probably pay the bills.
A1 is Level A: no AI-generated content in the submitted artifact.
A1 is graded as a standalone artifact: could another team design from it without talking to you?
Requirements for the project underpin all subsequent assignments.

From Problem Statement to Spec

You will usually get something like a PRD or a client prompt.
These are often underspecified, sometimes contradictory, silent on quality attributes.
- The ambiguity is not a defect you report. It’s the assignment.
- Every assumption you make to fill a gap must be written down, not just baked silently into your design.

Stakeholders

Who Cares About This System?

Before writing user stories, name who has a stake and what they actually want.

Role type	Concern
Users	Define functionality, ultimately use the system
Operators / admins	Run or moderate the system once deployed
Domain stakeholders	External parties with a real interest (e.g. campus facilities, a civil-engineering instructor)
…

A1 requires exactly three stakeholder roles, each with one goal and one concern. Extending-level work makes those goals conflict e.g. a reviewer wants openness, an operator wants to suppress abuse.

User Stories and Acceptance Criteria

User Story Form

As a <role>, I want to <capability> so that <benefit>.

A conversation starter, not a contract. Give just enough detail to scope and estimate.
Written in the stakeholder’s language, not implementation language.
A1 requires six stories: four functional, one error/edge-case, one administrative or operational.

Evaluating Stories: INVEST

Independent, Negotiable, Valuable, Estimable, Small, Testable

Split a story that hides multiple behaviours, roles, or quality concerns.
A story that can’t be tested isn’t ready.

Acceptance Criteria

Two per story, in testable language
something another team could check without asking you.
Bad: “the search should be fast and easy to use.”
Better: “given a destination with at least one bike park within 2 km, the response lists them ordered by distance.”

Example

As a student, I want to search for bike parks near a destination so that I can decide where to park before I arrive.

AC1: Given a destination that resolves to a known location, the response includes every bike park within a fixed radius.
AC2: Given a destination with zero bike parks nearby, the response is an empty list, not an error.

Lots of implementation options for these, but the Acceptance Criteria have a yes/no answer.

Quality Attributes

Beyond Features

Both model problems bury or omit non-functional requirements entirely.
A1 requires two quality attributes with testable criteria, not slogans like “the system should be secure.”
A fit criterion states how you will know the attribute is satisfied. It is a measurable or observable threshold.

Example Quality Attribute Criteria

idea: “the system should scale.”
QAS criterion: “the service returns search results within 500ms for a fixture of 500 bike parks and 50 concurrent requests.” (BikePark)
idea: “the simulation should be realistic.”
QAS criterion: “a 6-intersection map with two-way traffic settles into a stable pattern within 200 ticks without cars disappearing.” (Traffic Signal)

Tie the attribute to a stakeholder concern from your table. Why do we care about the stakeholder?

Domain Modelling

Glossary or Entity Model

Extract candidate entities, relationships, and states directly from the problem statement.
A1 wants 8-12 domain terms, or a small entity diagram with a short explanation.
The point is disambiguation: overloaded words (“park,” “review,” “phase,” “signal”) cause design confusion later if left implicit.
Mark unknowns and assumptions directly

Using GitLab to Manage Requirements

Why GitLab

A doc is a snapshot; requirements elicitation is a process.
GitLab issues give each story a home: discussion thread, labels, status, and a link back to acceptance criteria.
This is elicitation infrastructure. The graded artifact is still docs/a1-requirements.md — GitLab is where you work it out before you write it down.

Set Up the Project Board

In your team repo: Plan -> Work Items, or Plan → Issue boards.
Create labels before you create issues:
- story::functional, story::edge-case, story::admin — matches the A1 story categories
- stakeholder::<role> — one per stakeholder you’ve identified
- status::proposed, status::accepted, status::rejected — elicitation status
A board column per status label turns your issue list into a Kanban view of requirements decisions.

One Issue per Candidate Requirement

For each candidate user story or quality attribute, open an issue with:

Title: the story itself, in “As a … I want … so that …” form.
Description: acceptance criteria as a checklist (- [ ] AC1: …), plus any assumption it depends on.
Labels: story type and stakeholder.
Weight (Issues → set weight): rough size, if you want an early feel for scope.

Use GitLab’s Markdown checklists ( - [ ] ) — a story isn’t “done” being elicited until its acceptance criteria are checkable statements, and the checklist forces that.

Discuss and Refine in Issue Threads

Disagree about scope in the issue comments so it’s timestamped and attributable.
Use /label, /assign, and other quick actions to keep triage fast.
When a story gets split (INVEST: Small), close the original and open two new issues, cross-linked with Related to #<n> — GitLab renders this as a linked-issue graph, so you keep the split’s history instead of losing it in an edit.
When an assumption resolves an ambiguity, say so explicitly in the issue before closing it

Extracting Issues into A1

GitLab is not itself the submission — docs/a1-requirements.md is. Extraction is a deliberate step, not a copy-paste:

Filter the board by status::accepted.
Group accepted issues by story type (functional / edge-case / admin) — you need exactly six, in that split.
Pull each issue’s title into the story, its checklist into acceptance criteria.
Anything still status::proposed or contested becomes an open question, not a story — A1 needs exactly three.
Rejected issues aren’t wasted: a good rejection with a stated reason is evidence of scope control, worth a line in your out-of-scope list.

GitLab Also Answers “Where Did This Come From?”

Later assignments ask you to trace decisions: A2 traces to A1 quality attributes, A4 revises A1 stories under a change request.
Keep issues open (or reference their numbers) after extraction — a design decision in A2 that says “see #14” is stronger evidence than an unsupported claim.
This is the same instinct as an ADR: a decision is only as good as the reasoning you can still find later.

In-Lab / Studio Activity

From Problem to Issues to Spec

Choose one model problem — this is now your team’s problem for the term.
In GitLab: create the label set, then open 8-10 candidate issues (stories + quality attributes) from the PRD/prompt.
As a team, triage: label each status::accepted or status::rejected, splitting any story that fails INVEST.
Extract the accepted set into a first-pass docs/a1-requirements.md: stakeholders, six stories, acceptance criteria, two quality attributes, a domain glossary, three open questions.
Compare with another team on the same problem: what did they treat as central that you treated as incidental?

Before Next Lab

Read the full PROBLEM.md and README.md for your chosen model problem.
Have your GitLab board populated with at least the six candidate stories before the requirements studio lab.
Bring one open question you’re not sure how to resolve — that’s exactly what studio time and TA feedback are for.