Chapter 4 — The Requirements Nobody Writes Down

“Quality is value to some person.” — Gerald M. Weinberg, Quality Software Management, Vol. 1: Systems Thinking

“But he, desiring to justify himself, said to Jesus, ‘And who is my neighbor?’” — Luke 10:29 (ESV)

Why This Matters

Last week you wrote down what your system will do. Every functional requirement got an identifier, an actor, an action, a condition, a priority, and acceptance criteria a stranger could check. That is real work and you should be proud of it. It is also, on its own, dangerously incomplete. Because here is what a functional requirement never tells you: how fast, for how many people, on whose hardware, over what connection, holding whose data, readable by whom, recoverable from what, licensed under what terms, and maintainable by which poor soul comes after you. Those are the non-functional requirements — the qualities and the limits. Nobody asks for them in a meeting. Nobody writes them on a sticky note. And they are, with grim reliability, the reason capstone projects die in Week 13.

You are still wearing the business analyst’s hat this week, with a second hat on top of it: risk owner. You are in the last week of the requirements phase. Next week you start choosing technology, and you cannot choose technology sanely until you know what the technology has to survive. A stack that is perfect for a system with no auth and ten records is the wrong stack for a system that holds other people’s food inventory and has to load on a phone in a basement kitchen. Requirements first, then the stack. Every time you have seen it done the other way, you have seen a rewrite.

The AI thread runs hot this week from both directions. As a tool, this is one of the best uses an assistant has in the whole course: ask it to enumerate the non-functional requirements and legal obligations you have not thought of, and it will hand you a broader list than you would have written alone. It is a superb checklist generator. It is also a confident liar about licenses, regulations, vendor limits, and prices — the exact categories where being wrong costs money. As a workload, if your project ships user data to a hosted model, you have just acquired privacy requirements you did not have last week, and they must be written before the feature is. The spine rule holds: AI accelerates the enumeration; you verify every claim and you sign the document.

And the apologetic question this week is Luke’s lawyer’s question, asked in a code editor. Who is my neighbor when I write software? The lawyer asked it “desiring to justify himself” — hoping to draw a small circle. Software is very good at small circles. Your app will work beautifully on your machine, in your browser, at your eyesight, on your connection, with your six test records. Everyone outside that circle is a neighbor you will never meet, and the only place they exist before launch is in the requirements you write this week. So we are going to ask, seriously: how far does the circle go, and what does it cost you to widen it?

4.1 — Why the Requirements Nobody Writes Down Are the Ones That Sink Projects

A functional requirement says what the system does. A non-functional requirement says how well it does it, under what conditions, and what it must never do. The old industry nickname is the “-ilities” — reliability, usability, maintainability, portability, accessibility, security — and the nickname is part of the problem, because it makes them sound like garnish.

Look at the asymmetry:

A missing feature is an addition. A missing quality is usually a subtraction from an assumption the whole design rests on. You can bolt a new screen onto an app. You cannot bolt “works offline” onto an app that assumed a live connection at every keystroke, and you cannot bolt “supports two users” onto a data model with no notion of ownership.

Three families live in this chapter, and students routinely mash them together. Keep them apart:

1. Quality attributes — how well the system behaves. “p95 list load under 1.5 seconds with 200 records.” These have targets you measure.
2. Constraints — limits you did not choose and cannot change. “Total effort is capped at ~240 hours.” You do not “achieve” a constraint; you design inside it.
3. Obligations — what the outside world requires of you: license terms, API terms, data-handling duties. Not negotiable by you at all. Violating one is not a bug; it is a breach.

Here is the split for the running example, and for its opposite:

TraceLens has no user interface and still has an accessibility requirement. Every project has all eight categories; what changes is what they mean.

Coach’s Note — The most reliable predictor of a capstone that limps across the line in Week 16 is a Week-4 document that says “the system shall be secure and user-friendly.” That is not a low-quality requirement. It is not a requirement at all. It is a feeling, wearing a lab coat.

4.2 — Making a Quality Measurable: Metric, Threshold, Condition, Method

Tom DeMarco wrote, in Controlling Software Projects (1982), the line every engineering manager has quoted since: you can’t control what you can’t measure. Twenty-seven years later, in a 2009 IEEE Software essay, he publicly questioned how far he had taken it. Both halves are useful to you. Measurement is not the point — but an unmeasurable requirement gives you nothing to steer by at all.

So: four fields. Every non-functional requirement, no exceptions.

Three of those students will grudgingly write. The fourth — method — is the one they skip, and it is the one that makes the requirement real. A threshold with no method is a number you made up and will never test. Write the method and you have accidentally written next month’s test case.

A word on percentiles, because “average” is the wrong metric and students reach for it by reflex. If nineteen loads take 0.4 seconds and one takes 12, the average is a comfortable 1.0 second and one user in twenty just had a terrible time. p95 means “95% of measurements are at or below this value” — the bad-but-not-freak case, which is the case people quit over. Use p95 for anything a human waits on.

The gallery: four vague qualities, rewritten

Bad first, then why it fails, then the version you could be held to. This is the whole craft.

Bad: The system shall be fast. Why it fails: No metric, threshold, condition, or method. It cannot pass, cannot fail, cannot be tested, cannot be argued about. It will be quietly deleted in Week 12. Good: NFR-PERF-01 (Must) — The pantry list view renders a p95 of under 1.5 s with 200 seeded items on a throttled Fast 3G profile with a cold cache. Measured by: 20 loads in browser dev tools with throttling applied; p95 recorded in the measurements log each iteration.

Bad: The system shall be secure. Why it fails: “Secure” is a property of a whole system against a whole threat model. As one line it commits you to nothing, so it protects nothing. It is also compound — three requirements in a trench coat. Good: NFR-SEC-01 (Must) — No credential, API key, or token appears in the repository at any commit in history. Measured by: a secret-scanning step in CI over full history; zero findings. NFR-SEC-02 (Must) — Every write endpoint verifies server-side that the caller owns the target household. Measured by: one negative test per write endpoint asserting HTTP 403 for a non-owner.

Bad: The system shall be user-friendly. Why it fails: It measures your taste. Your taste is not evidence. Good: NFR-USE-01 (Should) — A first-time user, given only the task “add the milk in your fridge and set it to expire Friday,” completes it without assistance in under 3 minutes. Measured by: two observed sessions with people who have not seen the app; time and stumbles recorded in the usability notes.

Bad: The system shall be available 99.99% of the time. Why it fails: Roughly 52 minutes of downtime per year — on a free tier that idles your service after inactivity. You cannot deliver it, measure it, or even detect a violation. This is not ambition; it is a lie you will be graded against. Good: NFR-REL-01 (Must) — The deployed application answers a health check successfully on at least 29 of 30 consecutive daily checks during the final four weeks. Measured by: a scheduled check logging pass/fail to the measurements log.

Coach’s Note — Read your requirement out loud and ask: could two reasonable people disagree about whether we met this? If yes, you have written an opinion. Add condition and method until the disagreement is impossible.

4.3 — The Eight Categories, With Real Targets for a Student-Scale System

If your program requires a standard vocabulary, the usual reference is ISO/IEC 25010, the international product-quality model. What follows is a practical working set for a one-semester project — not a quotation of the standard, and deliberately smaller than it.

Two rules matter more than the table. One: do not copy enterprise numbers. Scale the target to what you can actually observe, as the availability rewrite in 4.2 shows. Two: the measurement must fit in an afternoon with tools you already have. If honoring a requirement needs load-testing infrastructure you will never build, the requirement will be ignored. A modest requirement you actually check beats a heroic one you never do.

Six of eight categories is the working minimum for this course. If a category truly does not apply, do not delete it silently — write one sentence saying why. “TraceLens has no authenticated users, so there are no authorization requirements; security here is about secrets and filesystem writes.” That sentence is worth as much as a requirement, because it proves you thought about it.

4.4 — Security and Privacy as Requirements, Not a Week 15 Panic

Security arrives in most capstones the way weather arrives in a bad plan: suddenly, in the last two weeks, and destructively. It arrives that way because it was never written as a requirement, so it was never on the board, so it was never scheduled.

Write it down now. Security requirements are the easiest to make verifiable, because most of them are prohibitions, and a prohibition is trivially testable.

• Secrets. No credential, key, or token appears in the repository at any commit. Configuration comes from environment variables; a .env.example with placeholder values is committed, the real .env is in .gitignore.
• Authorization on the server. Every write endpoint verifies ownership server-side. Hiding a button in the UI is not authorization — it is decoration over an open door.
• Input handling. All persistence uses parameterized queries or the framework’s query builder; no user string is concatenated into a query or a shell command.
• Passwords. Stored only as hashes from a maintained, memory-hard password-hashing library — not a hand-rolled SHA-256 loop. Better still, delegate sign-in to a provider and hold zero credentials.
• Dependencies and transport. Your package manager’s audit command runs in CI; anything deployed is served over HTTPS.

For a broader checklist, the OWASP Top Ten is the standard starting reference (https://owasp.org/www-project-top-ten/). Read the current list, pick what applies to your architecture, and turn each item into a requirement with a test. Do not paste the list in as-is; a copied list is not a requirement set, it is homework you photocopied.

The data inventory

Privacy starts with an embarrassingly simple table that almost nobody makes. Make it.

Two rows say verify and cite, and they are the two that matter. You do not know a vendor’s retention policy. Neither do I, and neither does an AI assistant. Read the vendor’s own page, write the URL and the date you checked into your requirements document, and move on. That habit — primary source plus date checked — is the single most professional thing in this chapter.

The AI workload: what leaves your machine

If your project sends user content to a hosted model — a recipe built from someone’s actual pantry, a summary of someone’s actual notes — you have created a data flow across a boundary you do not control. It needs requirements before it needs code:

• What may leave. Name the exact fields. Everything else is redacted or aggregated before the request is built, with a unit test on the request builder proving it.
• Consent and a fallback. The user is told, in the interface, that this feature sends their content to a third party, and chooses — buried disclosure is not consent. The feature degrades to something useful when they decline, when the provider is down, and when the free quota is gone.
• Retention and training terms. Whether a provider retains prompts, for how long, and whether inputs may be used for training varies by provider, by plan, and over time. Read the current terms, record URL and date, and design as if the answer could change — because it can.

Coach’s Note — Ask the roommate question: if the person whose data this is were reading over my shoulder while I wrote this line, would I write it the same way? For PantryPilot the roommates are literally the users. For your project, someone is.

4.5 — Accessibility: The Neighbor You Will Never Meet

Accessibility is the clearest case in all of software engineering where a requirement exists for a person who is not in the room, will never file your bug report, and will simply leave.

The reference standard is the W3C’s Web Content Accessibility Guidelines (WCAG), organized in conformance levels A, AA, and AAA. Level AA is the bar people actually contract to. WCAG 2.2 is the current W3C Recommendation as of this writing and 2.1 Level AA remains the most commonly cited contractual target; check https://www.w3.org/WAI/ for what is current before you cite a version.

You are not going to conform to all of WCAG in a semester, and I will not pretend otherwise. You are going to pick a handful of criteria covering the most common, most excluding failures, write them as measurable requirements, and actually check them. That is worth infinitely more than a document claiming “WCAG 2.1 AA compliant” that nobody tested.

Notice how many are measured by doing something for ninety seconds. Unplug the mouse. Turn the screen gray. Automated checkers are useful and you should run one, but they catch only a portion of real barriers — a machine can see a missing alt attribute; it cannot see that your alt text says “image1.png”. If your project has no graphical interface, accessibility changes shape rather than evaporating. For TraceLens: never signal severity with color alone (prefix the line with ERROR / WARN); honor the NO_COLOR convention and a --no-color flag so output survives a screen reader, a pipe, or a log file; keep default output within a reasonable terminal width and keep tables parseable when piped; use exit codes correctly so the tool composes with automation people already have. Write those down with the same four fields. A CLI has neighbors too.

Coach’s Note — Do the mouse-unplugged test in Week 9 on the walking skeleton, not in Week 15 on the finished app. Keyboard access is architectural; retrofitting it into a UI built entirely from click handlers is one of the more miserable weeks a developer can have.

4.6 — Constraints, Assumptions, and Dependencies — and the Difference

These three get mashed into one list called “notes,” and the mashing costs students real points and real weeks. Each is handled differently.

Worked, for PantryPilot.

Constraints — you did not choose these; stop arguing with them.

Assumptions — each one is a bet; price it.

Dependencies — they will fail; decide now what happens.

The move that saves students is the last column of the assumptions table. An unverified assumption is not a note — it is a bet you have not priced. Every ASM row either gets verified in Week 5, usually by a small spike (Chapter 5), or gets copied into the risk register in Chapter 7 with a probability, an impact, and a response. Nothing stays on the assumptions list forever.

Coach’s Note — Write the consequence column first. “If ASM-01 is false, barcode lookup becomes manual entry and I lose about six hours” turns a vague worry into a decision you make calmly in Week 5 instead of a crisis you discover in Week 12.

4.7 — Licensing, Data Rights, and What You May Legally Ship

Two separate questions. Students conflate them and answer neither.

What license goes on your project? In most jurisdictions a work with no license attached is not “free to use” — the default is that the author retains rights and nobody else has clear permission to copy, modify, or redistribute. A repository with no LICENSE file therefore says less than students think. If you want your capstone to be something you can show, share, and let someone build on, license it deliberately.

• Permissive (MIT, Apache-2.0, BSD family). Broadly: do what you like, keep the notice. Apache-2.0 additionally addresses patents and requires marking changed files. The common default for a portfolio project.
• Copyleft (the GPL family; the weaker LGPL/MPL variants). These attach conditions to how derived or combined work may be distributed. Whether and how those conditions reach your project depends on the specific license and on how the code is combined — and that is genuinely subtle. Read the license text, not a summary. Not mine, and not an assistant’s.

Authoritative starting points: the SPDX license list at https://spdx.org/licenses/ (canonical identifiers — MIT, Apache-2.0, GPL-3.0-only — which is what you write in your document) and https://choosealicense.com/ for plain-language orientation. If money, a real client, or your employer’s code is anywhere near this project, ask a human who knows. This book will not give you legal advice and neither will your chatbot.

What are you allowed to put in it? Everything you pull in carries terms:

Keep an attributions record in your repository from this week — every third-party asset, its source URL, its license identifier, the date you checked. Ninety seconds per entry now; a full day you will not have in Week 15. On the last row: the licensing and provenance status of code produced by generative models is contested and changing, and anyone who tells you it is settled is overselling. This course’s rule is not a legal opinion, it is an accountability rule — every AI-assisted contribution is disclosed in docs/ai-usage.md, and every generated line was read and understood by you before it was committed. You are the author of record. That rule is stable no matter how the law moves.

4.8 — The Traceability Matrix

A requirements traceability matrix is one row per requirement and a handful of columns that answer three questions no other artifact answers:

1. Is every requirement actually being built? A requirement with no design element is an orphan — you promised it and nothing in the system is responsible for it.
2. Is everything I am building actually required? Work with no requirement behind it is gold-plating — real hours spent on something nobody asked for.
3. Is every requirement tested? No test means no evidence, and no evidence means — for grading and for reality — it does not count.

The columns that earn their keep at this scale: req_id · type · priority · requirement · source · design_element · test_id · measurement_method · status. You start it this week with the design and test columns mostly holding placeholders. That is correct and expected. Week 6 fills the design column; Week 11 fills the test column. The matrix is the spine connecting Week 3’s promises to Week 16’s evidence.

An excerpt, from code/traceability-matrix.csv:

That sample is deliberately broken, and each break is a defect you should learn to see at a glance. FR-005 has no design element and no test — an orphan; design it or demote it, in writing. NFR-PERF-02 has a threshold but no measurement method — a wish in requirement clothing. The last row has a component and a test but no requirement — somebody is building an export button nobody asked for, and that is six hours you do not have.

Run the checker over it:

python3 check-traceability.py traceability-matrix.csv

traceability-matrix.csv: 17 rows, 8 findings

ORPHAN REQUIREMENT (2)
  - FR-005: no design element -- nothing in the system is responsible for it
  ...
UNMEASURABLE NFR (1)
  - NFR-PERF-02: no measurement method -- this is a wish, not a requirement

code/check-traceability.py is short on purpose — read it, then extend it. It exits non-zero when it finds a blocker, so once your matrix is supposed to be clean you can run it in CI and let the pipeline tell you when a new requirement sneaks in untraced.

Coach’s Note — Traceability is the difference between “I think I’m done” and “here is the evidence.” In Week 16 someone will ask whether you delivered what you promised. The student with a matrix answers in eight seconds. The student without one gives a tour of the app and hopes.

4.9 — The Definition of Done You Will Actually Be Held To

A definition of done is a single checklist that applies to every work item, not to the project. It is not the same thing as acceptance criteria: those are per-requirement and answer “does this feature do the right thing?” The definition of done is universal and answers “is this work finished to the standard we work at?”

Here is the bad version, and it is bad in the specific way that feels productive:

Definition of Done
- It works
- Code is clean
- Tested
- Documented if needed

Four items, zero of which anyone but the author could check. “It works” on whose machine? “Clean” by whose taste? “Tested” — how much, and did the suite pass? And “if needed” is where documentation goes to die, because it is never needed at 11 p.m. on the day you wrote the code.

Now the good version — same idea, made binary:

An item is Done when:
1. It traces to a requirement ID in docs/requirements.md.
2. Every acceptance criterion for that requirement passes when run, not when read.
3. At least one automated test covers the new behavior; the whole suite passes.
4. The pipeline is green on the merge commit.
5. No secret, key, or real user data was added to the repository.
6. The most likely failure path shows a message naming what failed.
7. New UI is keyboard-operable, labeled, and passes the contrast check.
8. Anything a stranger needs to know is in README.md, CHANGELOG.md, or docs/runbook.md.
9. AI assistance is recorded in docs/ai-usage.md; hours are logged the same day.

Every one of those can be answered yes or no by someone who is not you. That is the test of a definition of done. And then the rule that makes it worth having — the honesty rule: if you will not do it every time, take it off the list. A definition of done with an item you routinely skip is worse than none, because it trains you to treat written commitments as decoration. Eight to twelve items you genuinely honor beats twenty aspirational ones.

Start from code/definition-of-done.md, cut what you will not do, add what your project needs, and link it from README.md so a reader knows the standard your commits were held to. Notice that items 3, 4, 8, and 9 map straight onto lines of the Week-16 rubric. That is not an accident. The definition of done is the final grade, enforced weekly, by you.

4.10 — Using an Assistant to Find What You Missed (and Verifying Every Word)

Enumeration is exactly what these tools are good at: they have read more requirements documents than you ever will, and they will surface the category you forgot at 11 p.m. A prompt that actually works — note how much context it carries:

Here is the functional requirements section of my capstone project, plus my
one-paragraph project charter. [paste]

Act as a skeptical senior engineer reviewing this before a design review. List
the NON-FUNCTIONAL requirements and external obligations I have not written
down. For each: name the category; say what about MY project triggers it;
propose a measurable target with metric, threshold, condition, and measurement
method; and flag anything I must verify against a primary source. Do not invent
vendor limits, prices, license terms, or regulations — where a claim depends on
one, say "verify" and name the source I should read.

Then the part that is not optional. Three classes of claim get verified at the primary source before they enter your document:

Expect one specific failure, because it feels authoritative: the assistant will apply a real regulation to a project it does not govern and attach a real-sounding numeric threshold to it. It reads exactly like expertise. If a sentence about law or vendor terms enters docs/requirements.md without a link to a primary source and a date, delete it. A requirements document with a confident wrong legal claim is worse than one with a gap, because the gap is honest.

Roughly: it generates thirty candidates in two minutes, you keep twelve, you verify four at the source, and you own all twelve. That is the spine rule in its most useful form — AI accelerates, you decide, verify, and sign.

4.11 — Interactive Lab: The NFR & Traceability Builder

Below this chapter on the website is The NFR & Traceability Builder. Do it before you write your milestone; it is the rehearsal. The widget has two linked panels. In the first, you pick a non-functional category and turn a vague quality into a measurable requirement through guided fields — metric, threshold, condition, measurement method. Type “fast” and the widget will not let you off the hook; you will end up with something like p95 page load under 1.5 s on a 4G connection with 200 seeded records, and you will feel exactly where the vagueness was hiding. Do at least one requirement in each of six categories.

In the second panel you drag requirement identifiers onto design elements and test placeholders to build a traceability matrix. The widget then does what your eyes will not do reliably at 1 a.m.: it highlights orphaned requirements (promised, nothing responsible), untraceable design elements (built, nobody asked), and NFRs with no measurement method (decoration). Fix every highlight until the panel is clean. What it teaches, and what the milestone grades: that vagueness is not a style problem but a missing-field problem, and that a requirement is only real when something is responsible for building it and something is responsible for proving it. Copy your work out — you will want it twenty minutes from now.

4.12 — Who Is My Neighbor When I Write Software?

“But he, desiring to justify himself, said to Jesus, ‘And who is my neighbor?’” (Luke 10:29, ESV)

Read the motive, because Luke tells us plainly what it was. The lawyer had just been told to love his neighbor as himself, and he asked for a definition — desiring to justify himself. He was not asking for information. He was asking for a boundary. Tell me where the circle ends, so I can be finished, so I can be in the right.

Software is a remarkably efficient machine for drawing that circle small, and for doing it invisibly. You will build your project on your laptop, in your browser, at your screen size, with your eyesight and your reflexes and your fast connection and your six test records. Everything works. And every person outside that circle — the roommate on a five-year-old phone, the user with low vision, the person navigating by keyboard because a mouse hurts, the person on a rural connection, the person whose data you hold, the engineer who inherits this in eighteen months — is excluded not by any decision you made but by a decision you never made. No malice is required. The circle draws itself around whoever you happened to be.

The Levitical law understood this and legislated against it in the most physical terms possible. “You shall not curse the deaf or put a stumbling block before the blind” (Leviticus 19:14, ESV) — a prohibition against harming precisely the person who cannot see the harm coming and cannot protest afterward. And in Deuteronomy: “When you build a new house, you shall make a parapet for your roof, that you may not bring the guilt of blood upon your house, if anyone should fall from it” (Deuteronomy 22:8, ESV).

Sit with that second one, because it is a non-functional requirement written into a covenant. Nobody wanted a parapet. No one moving into a new house asked the builder for a railing; a parapet does not do anything, it merely prevents. The law imposed it on the builder anyway — because the builder is the only person in the story positioned to prevent the fall, and because the person who will fall is not yet known and cannot advocate for themselves. That is a security requirement. That is an accessibility requirement. That is your error-handling requirement and your data-deletion requirement. The obligation attaches to the one who builds, and it is owed to a stranger who is not present.

Notice how Jesus answers the lawyer. He does not. He tells a story and asks a different question: not who qualifies as my neighbor but “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 question is turned inside out — it stops being a category question, who is inside my circle of obligation, and becomes a character question: to whom will you be a neighbor? The lawyer wanted a definition that would let him stop. He was given a verb. And the priest and the Levite are worth a hard minute, because they are the characters most like a working engineer. Neither robbed anybody. Neither did anything wrong in the active sense. They passed by on the other side. Almost all the harm software does is passive harm of exactly that shape — nobody built an inaccessible form on purpose, nobody chose to leak the credentials, nobody decided the app should be unusable on a slow connection. It was not written down, so it was not built, so somebody was left on the roadside. Passing by is a decision; it is simply a decision made by not deciding.

Do not over-read this. Your capstone is not a moral emergency, and a missed contrast ratio in a student pantry app is not the parable of the Good Samaritan. But “one who is faithful in a very little is also faithful in much” (Luke 16:10, ESV), and the habits you build on a project with three users are the habits you carry into systems with three million. So this week’s work has a shape you can name: writing down the requirements nobody writes down is the act of naming your neighbor before you ever meet them — deciding, in advance and in writing, that the circle includes the person on the slow phone and the person who cannot see the screen and the person who comes after you. Build the parapet.

4.13 — Common Pitfalls

Pitfall: Non-functional requirements written as adjectives. Example: “The system shall be fast, secure, and user-friendly.” Fix: Four fields, always — metric, threshold, condition, method. If you cannot fill all four, you do not yet understand what you want. One adjective usually becomes three requirements; that is the process working, not failing.

Pitfall: Constraints, assumptions, and dependencies dumped into one list called “notes.” Example: “Notes: 240 hours, free hosting, roommates will test it, barcode API.” Fix: Three tables. Constraints bound the design. Assumptions get an owner and a verify-by date, and become risks if unverified. Dependencies get a pinned version, a named failure mode, and a fallback.

Pitfall: Security and privacy deferred to “when it’s working.” Example: Auth is scheduled for Week 13, the data model has no notion of ownership, and there is a real API key on line 4 of a committed config file. Fix: Write the prohibitions this week — no secrets in history, server-side authorization on every write, deletion that actually deletes — and put them on the board with the features. A secret committed in Week 6 is in your history forever, and “I deleted it later” is not a fix.

Pitfall: Accessibility treated as one automated scan. Example: A checker reports zero errors, so the box is ticked. Nothing is keyboard-reachable and every alt attribute says image. Fix: Run the scanner and do the ninety-second manual passes — unplug the mouse, set the display to grayscale, read the heading outline. Write those passes into your requirements as the measurement method so they get scheduled.

Pitfall: A traceability matrix built once in Week 4 and never opened again. Example: The matrix lists sixteen requirements; the app has eleven of them plus four things that appear nowhere in it. Fix: Update it whenever a requirement changes or a component is created — make that one line of your definition of done. Run the checker in CI so the pipeline nags you instead of the professor in Week 16.

Pitfall: A definition of done nobody, including you, will follow. Example: Fourteen aspirational items including “100% code coverage” and “full documentation,” honored roughly twice. Fix: Cut to eight items you will do every time. If you will skip it, it does not belong on the list. A short list you obey beats a long list you perform.

4.14 — Where Your Hours Went This Week

About fifteen hours, and this week is document-heavy:

If verification took three hours instead of ninety minutes, that is not a failure — that is you discovering that a vendor’s terms are not what you assumed, which is exactly what this week is for. Log it honestly. The hours log is only useful if it is true.

4.15 — Reps

This week’s reps are in the exercises, and they build the milestone piece by piece. Preview:

• Rep 1 — take five vague qualities from your own project and force each through the four fields.
• Rep 4 — write your data inventory and find the two rows where you do not actually know the answer.
• Rep 5 — the mouse-unplugged pass (or the CLI equivalent), with every stumble written down as a requirement.
• Rep 8 — sort a scrambled list into constraints, assumptions, and dependencies, then do the same for your project.
• Rep 11 — run code/check-traceability.py over the sample matrix, fix every finding, then run it over yours. Then take the on-page Check Your Reps quiz — the ungraded rehearsal for Week 4 Quiz in Canvas, and the early-warning system. If you cannot answer five questions about measurable requirements, you are not ready to write twelve of them.

4.16 — This Week’s Milestone

Milestone 4 — Milestone 4: Non-Functional Requirements, Constraints & Definition of Done. You will extend docs/requirements.md with a non-functional section of at least twelve measured requirements across at least six categories; add constraints, assumptions, and dependencies as three separate tables; record your license and third-party obligations with primary sources and dates; build docs/traceability.csv covering every requirement you have written since Week 3; and adopt a definition of done you will genuinely be held to.

Remember what the milestones are: they are graded twice, and that is not cruelty — it is arithmetic. They carry 25% on their own, and they are the final deliverable, produced one week at a time, so the Week-16 rubric pays for exactly these artifacts a second time. Falling behind is not a small penalty now; it is the milestone points lost and the same artifact points deferred to a week with no room left in it.

4.17 — Coach’s Final Word

Two weeks ago you had an idea. Last week you had a list of features. This week you have something much rarer in a student project and much more valuable: a written account of what “good” means for your system, in numbers, with the method for checking each one — plus an honest inventory of what you are betting on and what you owe to other people.

Most of your classmates will not do this. They will write “the system shall be fast and secure,” feel productive, and then spend Week 13 discovering that a demo which works beautifully on their laptop is unusable on the professor’s phone. You will know in Week 5 whether your assumptions are true, because you gave each one an owner and a date. You will know in Week 11 whether you hit your targets, because you wrote down how to measure them. And you will know in Week 16 that you delivered what you promised, because you can point at a matrix instead of giving a tour and hoping.

One last thing. Somewhere on your list this week is a requirement that exists for a person you will never meet — the keyboard user, the person on the slow connection, the engineer who inherits this. You will be tempted to cut it, because nobody is asking and nobody will complain if it is missing. Do not cut it. That requirement is the parapet, and building the parapet is the whole job.

See you on Monday.

Up next: the exercises drills the four fields, the three tables, and the matrix · Milestone 4 is Milestone 4 · then Chapter 5 — where you finally choose the technology, evaluated against the requirements you just wrote. Reference: Appendix B (the document kit — templates and worked good/bad examples), Appendix C (the grading contract and Week-16 rubric), Appendix E (glossary). Previous: Chapter 3.