Milestone 4 — Non-Functional Requirements, Constraints & Definition of Done

“Which of these three, do you think, proved to be a neighbor to the man who fell among the robbers?” — Luke 10:36 (ESV)

Chapter: Chapter 4 — The Requirements Nobody Writes Down Week: 4 of 16 Due: End of Week 4, before your Week-5 session. Late work is not a small penalty — it is the same points, moved to a week with no room in it. Submit: A commit (or a merged pull request) on your capstone repository, plus the commit SHA in the Canvas dropbox. Where it lands in the final package: docs/requirements.md section 6 plus new sections 10–13, docs/traceability.csv, and docs/definition-of-done.md — all part of the Week-16 submission that carries 50% of your grade. This milestone feeds the requirements specification line of the final rubric and, through traceability, the verification evidence line. See Appendix C for the full grading contract. AI policy: Open, with disclosure and verification. Use an assistant to enumerate candidates and to stress-test your wording. Every requirement you keep must carry a measurement method you can actually run, and every claim about a license, a regulation, a price, or a vendor limit must be verified at the primary source with a URL and a date. Record what you used and what you had to correct in docs/ai-usage.md. You are the author of record.

The Setup

Your Week-3 requirements document says what your system will do. Right now, a reviewer reading it could build something that satisfies every line of it and is still unusable: nine-second page loads, an API key in the repository, a form nobody can reach with a keyboard, a chart library whose license forbids what you are about to do with it, and no way for anyone to tell whether any of that is a problem, because nothing in the document is measurable.

This week you close that hole. You are writing the second half of the requirements specification — the qualities, the limits, and the obligations — and then two artifacts that make the whole thing enforceable: a traceability matrix that connects every promise to something responsible for keeping it, and a definition of done that applies to every piece of work you do for the next twelve weeks.

There is a specific reason this is Week 4 and not Week 12. Next week you choose your technology. A stack is not “good” or “bad” in the abstract; it is good or bad against a set of requirements. Choose the stack first and you are choosing by fashion, by what a job posting mentioned, or by what an assistant recommended to somebody else. Choose it after this milestone and you are choosing against a written specification you can defend in a design review.

And there is a second reason, less about grades. The requirements you write this week are the only place, in the entire project, where the people you will never meet get a vote.

Learning Targets

You will demonstrate that you can:

• Convert vague quality statements into non-functional requirements with a metric, a threshold, a condition, and a measurement method.
• Cover the quality landscape deliberately — choosing categories with a stated reason, and saying why the ones you skipped do not apply.
• Set targets that are defensible at your scale, rather than copied from an enterprise service-level agreement you cannot measure.
• Specify security and privacy as testable prohibitions, including a data inventory that says what you hold, for how long, and how someone gets rid of it.
• Write accessibility requirements for users you will never meet, with manual verification methods.
• Distinguish constraints from assumptions from dependencies, and handle each correctly.
• Verify obligations at primary sources — licenses, terms of service, data rights — and cite them with dates.
• Build a traceability matrix and resolve every orphan, gold-plated item, and unmeasurable requirement.
• Adopt a definition of done you will genuinely be held to, and defend the items you cut.

The weekly status block — paste this into your submission comment

Every milestone submission carries these five lines. It takes two minutes, it is the same five lines every week, and it is the difference between an instructor who can help you in Week 6 and one who finds out in Week 14. Copy it into the Canvas submission comment when you submit — not into a document.

Shipped:     what actually works this week, in one line
Cut:         what I dropped or deferred, and where it went (backlog / change request / gone)
Hours:       planned N / actual N        (from docs/hours-log.csv)
Blocked on:  the one thing in my way, or "nothing"
Ship confidence: green | amber | red — if amber or red, the one thing that would move it

Say red when it is red. A red in Week 6 is a conversation and a scope cut. A red discovered in Week 15 is a grade. Nobody has ever been penalised in this course for an honest amber; the only expensive answer is the green that was not true.

Normal Tier

Required deliverables

Everything below lands in your repository. Filenames matter; a reviewer should not have to hunt.

You are extending the document you wrote in Week 3, not starting a second one. Sections 1–9 already exist and stay where they are: §5 is your functional requirements, §7 your out-of-scope table, §8 your open questions, §9 your change log. This week you fill the §6 placeholder the Week-3 template left for you and append new sections 10–13. Do not renumber anything from Week 3 — the Week-16 rubric and your traceability matrix key off those numbers.

1. docs/requirements.md, section 6 — Non-Functional Requirements. At least twelve non-functional requirements spanning at least six of the eight categories (performance, reliability, security, privacy, accessibility, usability, maintainability, portability). Every requirement carries:

• a stable identifier in a scheme you keep for the rest of the course (e.g. NFR-PERF-01);
• a priority (Must / Should / Could, consistent with your Week-3 MoSCoW scheme);
• all four fields — metric, threshold, condition, method;
• a measurement method you can actually run with tools you have.

For each of the two-plus categories you did not use, one sentence saying why it does not apply to your project. “Not applicable” alone earns nothing; the sentence is the work.

2. docs/requirements.md, section 6.x — Security and privacy. Included in the twelve above, but called out because it is graded separately: at least three security requirements written as prohibitions with tests, and a data inventory table — every data element you touch, why you need it, where it lives, how long you keep it, and how a user gets rid of it. Rows you cannot answer from your own knowledge are marked verify and carry the primary source you will read.

3. docs/requirements.md, sections 10–12 — Constraints, assumptions, dependencies. Three separate tables. At least four constraints with what each rules out. At least four assumptions, each with an owner, a verify-by date, and the consequence if it turns out false. At least three dependencies, each with a pinned plan or version, a failure mode, and a fallback.

4. docs/requirements.md, section 13 — Obligations. Your project’s license position, stated one of two ways. Either the license you have already chosen — named by its SPDX identifier here, with the LICENSE file present at the repository root — or the dated deferral you wrote in Week 1, restated in this section with the two candidate licenses you are deciding between and the question that will settle it when you make the call in Week 5. Both earn full credit; an unstated position earns none. Plus every third-party obligation you currently know of — library licenses, API terms, asset and dataset terms — each with the primary source URL and the date you checked it. At least one obligation must have been verified at its primary source this week, not assumed.

5. docs/traceability.csv. Every requirement you have written since Week 3, functional and non-functional, in one file with the columns from code/traceability-matrix.csv. Design and test columns may hold placeholders this week, but not blanks. Running code/check-traceability.py against it must either exit clean or be accompanied by a short written justification for each remaining finding.

6. docs/definition-of-done.md. Eight to twelve items, every one answerable yes-or-no by someone who is not you, linked from README.md. Include a short note listing what you cut from the template and why.

7. An updated hours log. Week 4’s hours, recorded honestly, in the log you set up in Appendix A. Estimated-versus-actual matters more than the total.

What this looks like when it is right, and when it is not

A grader can tell in ninety seconds. Here is the difference, on one requirement:

# Failing
NFR-3  The app must be fast and secure.

# Passing
NFR-PERF-01 (Must) — The pantry list view renders a p95 under 1.5 s with 200
seeded items on a throttled Fast 3G profile, cold cache.
Measured by: 20 loads in browser dev tools with throttling applied; p95
recorded in docs/measurements.md each iteration. Traced to: PantryListView,
T-101.

And on one assumption:

# Failing
Notes: hopefully the free hosting tier lasts the semester.

# Passing
ASM-02 — Free hosting keeps the app reachable for a live demo through Week 16.
Owner: me. Verify by: Week 5 (deploy the walking skeleton and leave it up
for 72 hours). If false: demo from a local run and record a fallback video
in Week 15. Escalates to RISK-04 if unverified by Week 7.

Normal-tier rubric (out of 100)

Medium Tier (+ up to 25% extra credit)

Take the specification from “written” to “already partly proven.” Pick what fits your project:

• Measure three NFRs for real, now. Even against a stub or a wireframe, record a baseline in docs/measurements.md with the date and the conditions. A target with a starting number beside it is a target you will actually chase.
• Write executable placeholders. Turn at least four requirements into skipped or pending test stubs in your repository, named for the requirement identifier (test_nfr_perf_01_list_p95). They fail loudly in Week 11 if you forgot them.
• Draw the data-flow diagram. Every place personal data enters, rests, moves, and leaves — including any hop to a third-party model. One diagram, exported to an image, embedded in the requirements document.
• Run a peer walkthrough. Hand your matrix and your NFR section to a classmate for fifteen minutes with one instruction: find the requirement you could not verify if you had to. Record what they found and what you changed.
• Automate the gate. Wire code/check-traceability.py into your CI so a pull request fails when a requirement loses its trace.

Hard Tier (+ up to 25% additional extra credit)

This tier is judgment, and judgment does not delegate. Write a two-to-three-page “Obligations and Tradeoffs Memo” addressed to a reviewer who will inherit this project. It must do four things an assistant cannot do for you:

1. Name the non-functional requirement you are deliberately going to under-deliver on, and defend the choice. Not “I’ll try to do everything” — pick one, say what you are trading it for, say who it costs, and say what would make you change your mind. A capstone that claims to be excellent in all eight categories is a capstone whose author has not made a decision yet.

2. Name the group of users your project will serve worst, concretely — people on old devices, people with low vision, people on metered connections, people who read a language you are not supporting, people using assistive technology. Estimate what it would cost in hours to serve them meaningfully. Then say what you are doing about it in the time you have, and be honest if the answer is “nothing this semester.” An honest “not this time, and here is what it would take” is worth full marks. A vague claim of inclusivity is worth none.

3. Make the licensing and data call, with primary sources. State the license you have chosen and why that one rather than the other family — or, if you are still deferring the choice to Week 5, name the two families you are deciding between and the specific question that will settle it. State what your obligations are toward every third-party thing you are shipping, citing each primary source with the date you read it. If any of it is genuinely unclear to you, say so and name who you would ask — that is a professional answer, not a failure.

4. Account for the assistant. Where did AI help this week, where did it produce something you had to discard, and what specifically did it get wrong? Name one claim it made that you verified and found false, or state plainly that you verified every claim and found none wrong — and then say how you verified them. Vague disclosure is not disclosure.

Graded on honesty, specificity, and self-awareness. A memo that admits a real weakness and defends a real tradeoff scores far above one that reports everything is fine.

Submission

Your repository should look roughly like this by the end of the week:

docs/
├── requirements.md          # §1–9 from Week 3; §6 filled in and §10–13 added this week
├── traceability.csv         # every FR and NFR, traced
├── definition-of-done.md    # 8–12 binary items
├── measurements.md          # Medium tier: baselines with dates
├── ai-usage.md              # what you used, what you corrected
└── obligations-memo.md      # Hard tier only
LICENSE                      # the chosen license matching §13, or the dated deferral note
README.md                    # links the definition of done

Submit the commit SHA (or the merged pull request link) to Canvas. Do not submit a zip file, a document attachment, or a link to a folder in cloud storage. The repository is the deliverable, from Week 1 onward.

Hints

• Do the reps first. the exercises produces most of this milestone as a side effect. Rep 1 gives you the performance and usability requirements, Rep 4 the data inventory, Reps 5 and 6 the accessibility requirements, Rep 8 the three tables, Rep 11 the matrix, Rep 12 the definition of done. Skipping the reps and writing the milestone from scratch is the slow path.
• Start from the templates. code/nfr-template.md has every section with the right columns; code/definition-of-done.md has a starting list plus the bad version to compare against. Delete the instruction lines before you commit.
• Paste into the Week-3 numbering, not over it. The non-functional tables replace the §6 placeholder; constraints, assumptions, dependencies, and obligations become §10, §11, §12, and §13 at the end of the document. If you end up with two sections numbered 5, you have overwritten your functional requirements — and a little further down, your out-of-scope table, open questions, and change log, which Milestone 3 was graded on and which Week 8’s review package reads from.
• Write the measurement method first. If you cannot write the method, you do not yet know what the threshold means. Method → condition → threshold → metric works better than the reverse for anything you are struggling with.
• Twelve is a floor, not a target. But twelve good ones beat twenty-five padded ones; a reviewer who finds three unverifiable requirements starts doubting the other twenty-two.
• Do the verification early in the week. Reading a vendor’s actual terms takes longer than you think, and it sometimes changes your plan — which is much cheaper to discover on Tuesday than on Sunday night.
• Keep the identifiers stable forever. NFR-PERF-01 means the same thing in Week 16 as it does today. Renumbering breaks your matrix, your test names, and your Week-16 evidence. If a requirement dies, mark it withdrawn; do not reuse its number.
• Do not let the assistant write the measurement methods unsupervised. It will confidently propose load tests, synthetic user studies, and monitoring stacks you will never build. If the method does not fit in an afternoon with tools you already have, rewrite it.

What Mastery Looks Like

A mastered Milestone 4 reads like it was written by somebody who expects to be held to it. There is not one adjective in the whole document standing on its own. Every threshold has a unit and a condition, and every requirement ends with how anyone — not just the author — could check it. The security section is a list of things that must never be true, each with a test. The data inventory has a row for something the author clearly did not want to think about, and it is filled in.

The three tables are separate and correct, and the assumptions table has dates in it — real dates, next week, with a name beside them. The obligations section cites primary sources with dates, and at least one entry says something the author admits they did not expect.

The matrix runs clean, or the findings that remain have a sentence each explaining the decision. And the definition of done is short — visibly shorter than the template — because the author went through it and deleted the items they knew they would skip. That deletion is the tell. It is the difference between a student writing what sounds good and an engineer writing what they intend to do.

Coach’s Note — The moment that decides your grade on this milestone is not a moment of writing. It is the moment you read a requirement you just wrote, realize you have no idea how you would test it, and go back and fix it instead of moving on. Everyone gets to that moment. Almost nobody stops.

When You’re Done

• Twelve or more NFRs, six or more categories, four fields on every one
• A written sentence for each category you skipped
• Three-plus security prohibitions, each with a test
• Data inventory complete; unknown rows marked verify with a primary source named
• Accessibility requirements with manual verification methods
• Constraints, assumptions, and dependencies in three separate tables
• Every assumption has an owner, a verify-by date, and a consequence
• Every dependency has a failure mode and a fallback
• License position stated in §13 — SPDX identifier with LICENSE at the repo root, or the dated Week-5 deferral with its two candidates named
• At least one obligation verified at a primary source, with URL and date
• docs/traceability.csv covers every requirement; the checker runs clean or findings are justified
• Definition of done: 8–12 binary items, linked from README.md, with a note on what you cut
• docs/ai-usage.md updated with what you used and what you corrected
• Hours logged honestly, including the parts that took longer than expected
• Everything committed with real commit messages

A theological footnote. The lawyer asked “who is my neighbor?” and Jesus answered with a different question: “Which of these three, do you think, proved to be a neighbor to the man who fell among the robbers?” (Luke 10:36, ESV). The lawyer wanted a boundary; he was given a verb. That reversal is the whole of this milestone. You could treat non-functional requirements as a compliance exercise — a list to satisfy so you can be finished, so you can be in the right. Or you could treat them as what they actually are: the one place in your project where you decide, before anyone can ask you to, whose needs will count. The parapet on the roof in Deuteronomy 22:8 was owed to a stranger who had not yet fallen, by a builder who would never meet them. That is a requirement nobody writes down, imposed on the only person in a position to prevent the harm. This week, you are that person. Write it down.