Skip to content
CS Capstone Handbook

Project Requirements

Read this before writing docs/requirements.md and whenever scope grows in a partner meeting; it gives you the shape of a requirement a teammate can test.

Requirements say what the product must do and how well, in language a teammate can test. They live in your repository as docs/requirements.md, next to the code rather than in a separate document nobody opens, and they are the file your AI tools read before they build anything. Without clear requirements:

  • Developers build the wrong feature well.
  • Scope grows in every partner meeting because nothing was written down to push back against.
  • “Done” is argued at the demo instead of settled at the start of the sprint.
  • There is no agreed target to measure “shipped” against, so nobody can say whether the project succeeded.

A requirement is a specific, testable statement about the product. It is not a wish (“the app should be fast”), a task (“build the login page”), or a design decision (“use PostgreSQL”). Tasks go on the board; decisions go in an ADR.

What Is a Requirement?

Section titled “What Is a Requirement?”

Three kinds cover almost everything a Capstone project needs:

  • Functional: what the system does. “A user can reset their password by email.” “The pipeline rejects a record whose timestamp is missing.”
  • Non-functional: how well it does it, with a number. “The dashboard loads in under 3 seconds on a campus connection.” “A fresh clone runs the full pipeline in one documented command.”
  • Constraints: limits you did not choose. “Must run on the partner’s existing Postgres 14.” “No personal data leaves the partner’s network.” “Ships under the upstream project’s license.”

The longer taxonomies in textbooks (user, system, business, domain) are ways of asking whose requirement it is. Useful in an interview, not as headings in your document. If you want the formal version, ISO/IEC/IEEE 29148 is the international standard for requirements engineering, and it is a useful thing to have looked at once: it shows you what full rigor costs, which is the context you need to understand why almost nobody outside safety-critical work pays it.

User Story Mapping is the fastest way to produce a first real version of the file, and the rest of this guide is about keeping it worth reading afterwards.

Requirements come from talking to people: your partner, the people who will use the thing, the maintainers whose project you are joining. Interviews, a few observed sessions, and a look at what competitors already do cover most of it. Then write them down, get them checked, and expect them to change.

Addressing a Problem

Section titled “Addressing a Problem”

The best projects address a problem for a group of people you can name. A clear problem gives you a reason for every requirement and a way to say no to the ones that do not serve it.

So the document opens with a problem statement: what the problem is, who has it, why it matters, and what evidence you have that it is real. One paragraph. It is the most-read part of the document and the one that changes most often: strong teams re-frame the problem as they learn, and say so in the file’s history.

Problem Statement TemplateOne-sentence statement, affected roles, evidence, and the lenses you framed it through.
Creative ActivitiesActivities to uncover, frame, and re-frame the problem.

What Makes a Good Requirement?

Section titled “What Makes a Good Requirement?”

A good requirement is one a teammate could mark passed or failed without asking you. That means specific nouns, a measurable bar for anything about quality, and an acceptance criterion wherever the behavior is not obvious. This single property, testability, does more work than any template: “the system should be fast” cannot be checked and so cannot be finished, while “the dashboard loads in under three seconds on a campus connection” can be both.

Two conventions are worth knowing because you will meet them. User stories in the “as a, I want, so that” form are popular because the third clause forces you to state the benefit, which is where vague requirements usually collapse; the INVEST mnemonic is the usual checklist for whether a story is well formed. Given-When-Then, formalized in Gherkin, is the same instinct applied to acceptance criteria, and it has the pleasant property of translating almost directly into a test. Neither is required here. Both are better than prose when a requirement has conditions. This is the shape of a docs/requirements.md that stays worth reading:

# Requirements


## Problem statement
Volunteer coordinators at <partner> schedule about 40 shifts a week in
a spreadsheet and email; double-bookings happen weekly (three last
month, per the coordinator). We are building a shift board that
prevents them.


## Functional requirements
- FR-1: A coordinator can create a shift with a date, time range,
  location, and headcount. Acceptance: a shift whose end time is
  before its start is rejected with a message.
- FR-2: A volunteer can claim an open shift. Acceptance: a second
  claim on a full shift fails, and the shift shows as full within 5 s.
- FR-3: A coordinator is emailed when a claimed shift is released
  within 24 hours of its start.


## Non-functional requirements
- NFR-1: The board loads in under 2 s on the partner's office Wi-Fi.
- NFR-2: Usable with a keyboard alone; axe-core reports no serious
  violations (WCAG 2.2 AA).


## Constraints
- C-1: Sign-in through the partner's existing Google Workspace; no
  new accounts.
- C-2: Volunteer names and emails never leave the partner's tenant.


## Non-goals (this year)
- Payroll or hours export.
- A native mobile app; the board is responsive web.


## Open questions
- Does v1 need recurring shifts? Owner: PM, before sprint 2.

Number the requirements so a pull request, a test, or a sprint note can cite one. Write a functional requirement as a user story (“As a coordinator, I want to… so that…”) where the why is not obvious, and as a plain statement where it is. Give every non-functional requirement a number and a way to measure it, or it is a wish.

Rank them. MoSCoW or an impact-effort pass (Planning guide) is enough; the point is that the top of the list is what the next sprint pulls. The non-goals section is the cheapest scope control you have: it turns “we did not think of that” into “we decided against that”, which is a different conversation with a partner.

Track the list on your board, not in a second document. GitHub Projects is enough; Linear, Jira, and Notion also work.

Story Mapping

Section titled “Story Mapping”

A user story map lays the user’s activities left to right in the order they happen, and the stories that serve each activity top to bottom by priority. A horizontal line through the map is a release: everything above it ships, everything below waits. It is the fastest way to turn a pile of stories into a docs/requirements.md with a defensible “this year” line, which is why User Story Mapping is worth running as a team rather than reading about. The stories above the line become your functional requirements; the line itself is the first draft of what you are committing to ship.

Validation

Section titled “Validation”

A requirement is validated when someone other than the author has confirmed it. The cheap confirmations:

  • The partner read it. Review the document with your project partner or mentor early, and again after any re-framing. Misunderstandings surface here every year; the review costs an hour and the misunderstanding costs a term.
  • A prototype hit it. A clickable mockup or a walking-skeleton slice tests a requirement faster than another meeting, and tells you whether the thing is feasible at the same time.
  • A test names it. When FR-2 has a test called test_second_claim_on_full_shift_fails, the requirement is re-validated every time CI runs.

Four questions per requirement: is it valuable to the user, usable by them, feasible to build, and viable for the partner? A no on any of them means cut or rewrite, not keep out of politeness.

Measuring Success

Section titled “Measuring Success”

The problem statement says what you are fixing; success metrics say how you will know. Two or three, each with a number, a decision rule, and a collection method, written before you look at any data. What they count depends on your outcome type: a product counts strangers who came back, a consultancy counts the partner’s people using it, a FOSS contribution counts merges, a research project answers its questions. The Planning guide has the frameworks; Identify Success Metrics is the exercise, and the result belongs next to the requirements it judges.

Best Practices for Writing Requirements

Section titled “Best Practices for Writing Requirements”
  • Back each requirement with something: a partner quote, an observed session, a competitor that does it, a number. “The coordinator asked for it” is evidence; “it seemed useful” is not.
  • Use a picture where a paragraph struggles. A wireframe or a flow diagram next to FR-3 saves three rounds of clarification.
  • Update the file when the requirement changes, in the same pull request as the code. A requirements document that lags the code is read once and never again.
  • Keep the problem statement and the non-goals at the top. They are what a reviewer, a new teammate, and your AI tool need first.
  • Prioritize, and write the reason next to the rank.
  • Separate requirements from decisions. “Must store data durably” is a requirement; “use PostgreSQL” is an ADR.
  • Split any requirement with “and” in it.
  • Say what you do not know. An open-questions section with owners is honest; a confident requirement you never checked is a bug waiting to be discovered by someone else.

Some Truths about Software Requirements

Section titled “Some Truths about Software Requirements”

A requirements document can absolutely be busywork, and the version that becomes busywork is recognizable: long, unranked, written once, stored somewhere other than the repository. It gets abandoned within a month because nothing in the team’s daily work touches it. The version that survives is short, ranked, and sitting next to the code, where a pull request can change it in the same commit that changes the behavior.

Expect most of it to be wrong at first, and treat that as the normal condition rather than a failure of analysis. Requirements are guesses about what people need until a user or a partner confirms them, and the guesses made in fall week 3 are made by a team that has not yet watched anyone use anything. This is why the document needs a way to mark which items are confirmed and which are assumed; an unconfirmed requirement that looks identical to a confirmed one is how teams build the wrong thing with total confidence.

The staleness question deserves a straight answer, because teams ask it every year and the usual advice dodges. Once your board holds the current work and your tests encode the acceptance criteria, the functional list genuinely does become redundant, and maintaining it in parallel is duplicated effort that will drift. What does not become redundant is the part the board never holds: the problem statement, the non-goals, the non-functional bars, and the open questions. If you let the functional list lag behind the board, that is a defensible trade. If you let those four go stale, you have lost the only record of what you decided not to do and how good it has to be, and both will be asked about in spring.

Safety-critical, regulated, and hardware projects are the real exception, and it is worth understanding why rather than filing it as a caveat. When the cost of a late change is enormous, moving discovery earlier is worth almost any amount of paperwork, so the document becomes a contract and the formality is the point. Your project is almost certainly not in that category. If it is, your partner will tell you, and the standard above stops being background reading.

Requirements in Industry and Academia

Section titled “Requirements in Industry and Academia”

In industry the artifact is the product requirements document (PRD): features, behavior, constraints, and success metrics, kept by a product manager and read by engineers, designers, and leadership. Amazon starts earlier still, with a PR/FAQ: a one-page press release written as if the product had already shipped, followed by the questions a skeptical customer or executive would ask. Both exist for the same reason your problem statement does: to force agreement on what is being built before anyone builds it.

In research the equivalent is the research question and the pre-registered analysis plan; in open source it is the issue discussion that precedes a substantial pull request. Every mature field has learned to write the requirement down before the work, because the alternative is discovering it at the demo.

Additional Readings

Section titled “Additional Readings”

Requirements writing has a formal tradition and an agile reaction to it, and the useful position for a capstone team is somewhere between. The standard is here so you know what full rigor looks like; the story and acceptance-criteria references are what you will actually use.

Sources and further reading

  • ISO/IEC/IEEE 29148: the international standard for requirements engineering, worth seeing once.
  • User Stories, Mike Cohn: the format, what it is for, and its limits.
  • INVEST: the checklist for whether a story is well formed.
  • GivenWhenThen, Martin Fowler, and the Gherkin reference: acceptance criteria in a form that becomes a test.
  • User Story Mapping, Nielsen Norman Group: the technique, and how a horizontal line through the map becomes a release.
  • Writing requirements, Jama Software: practical guidance on phrasing, from a requirements tooling vendor.

Activities that exercise this