Milestone 2 — Software Requirements Specification

“Like clouds and wind without rain is a man who boasts of a gift he does not give.” — Proverbs 25:14 (ESV)

Chapter: Chapter 2 — Requirements at Speed Week: 2 of 8 · Life-cycle phase: Requirements · Hat: business analyst, with risk owner on top of it Due: End of Week 2, before your Week-3 session. In an eight-week course a week is an eighth of the term; late is not a small penalty, it is the same points moved into a week that is already full. Submit: Committed and pushed to your capstone repository, tagged milestone-2, with the commit SHA in the Canvas dropbox. Nothing is emailed and nothing is zipped. The repository is the submission, from Week 1 onward. Where it lands in the final package: docs/requirements.md, docs/traceability.csv, docs/definition-of-done.md, and docs/elicitation-notes.md — all part of the Week-8 submission that carries 50% of your grade. This milestone feeds the final rubric’s requirements specification line directly and, through traceability, its verification evidence line. Week 3’s architecture decision records answer this document. Week 4’s design review audits you against it. Week 6 tests exactly what it promised. AI policy: Open, with disclosure and verification. An assistant may ask you questions, enumerate cases you missed, and attack a sentence for ambiguity. It may not author a requirement. Every claim about a license, a price, a vendor limit, or a regulation is verified at the primary source with a URL and a date. Log every substantive use in docs/ai-usage.md — tool, what you asked, what you kept, what you discarded and why. You are the author of record.

The Setup

You are holding a set of drafted requirements written by somebody who has never met you. They are good requirements. They are well formed, they use shall correctly, they have acceptance criteria, and every one of them was written for a project that is not exactly yours.

That is the trade this edition made on your behalf. The sixteen-week course spends two weeks and thirty hours getting a student from a blank page to a specification. You got the page pre-filled, and in exchange you accepted a specific and non-obvious risk: a requirement that quietly describes somebody else’s project looks exactly like one that describes yours. It passes the linter. It reads professionally. It will be built in Week 5 by a version of you who no longer remembers that it came from a template, and it will be discovered in Week 6, when there are no hours left to rebuild it.

So this milestone is graded on two things at once. The first is the standard every capstone specification is graded on: could somebody else build this and hand you back the thing you meant? The second is this edition’s: did you decide about every sentence in it? Keep is a decision. Adapt is a decision. Withdraw is a decision. Drift is not, and drift is what the Adaptation Record exists to make visible.

Write it as if you were handing the project to a competent engineer you will never speak to. In a real sense you are. That engineer is you, six weeks from now, tired, with a deadline visible, and they will have nothing but what you wrote down.

Learning Targets

You will demonstrate that you can:

• Adapt an inherited requirement set — keep, adapt, split, or withdraw every line, with a written reason.
• Detect the inherited requirement that no longer matches your project, by hand and by tool.
• Write functional requirements that are unambiguous, verifiable, singular, and free of implementation.
• Specify acceptance criteria a stranger could execute and get an unambiguous pass or fail.
• Convert vague quality words into non-functional requirements with a metric, a threshold, a condition, and a measurement method you can actually run.
• Separate constraints from assumptions from dependencies, and handle each correctly.
• Prioritize with MoSCoW and with hours — defending your Must list against thirty hours of net feature construction.
• Specify a probabilistic feature, if you have one, by its envelope, guardrails, fallback, and fixed evaluation set.
• Verify an obligation at its primary source and cite it with a date.
• Use an assistant inside the spine rule — it asks, you decide — and disclose that use accurately.

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 3 and one who finds out in Week 7. 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 3 is a conversation and a scope cut. A red discovered in Week 7 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

The bar. This is what a complete, professional requirements specification looks like at accelerated-capstone scale — everything the long edition demands, sized to 160 hours.

Required deliverables

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

1. docs/requirements.md, built from code/srs-template.md, with all thirteen sections present and none empty. Nothing is deferred to a later week; there is no later week for this.
2. Twelve to twenty-two functional requirements. Below twelve, a 160-hour project is almost certainly under-specified; above twenty-two, you are specifying at a level of detail that belongs in next week’s technical specification. If your project genuinely falls outside the band, say so in §1 and defend it in two sentences.
3. Every requirement carries all six parts — identifier in one consistent scheme, actor, action, object, condition, priority — plus a rationale line, a Source: line, and an Adaptation: verdict (Kept, Adapted, Split, Withdrawn, or New).
4. Every Must and Should carries at least two acceptance criteria in Given/When/Then form: one happy path, one thing going wrong.
5. §4, the Adaptation Record. Every requirement your brief handed you, with its verdict, your identifier, and the reason. Withdrawn rows keep their number and carry a dated one-line reason. Students who brought their own project record what they took from the brief they used as a template, and what they did not.
6. Eight or more non-functional requirements across five or more categories, every one with metric, threshold, condition, and method. For each category you skipped, one sentence saying why it does not apply. “Not applicable” alone earns nothing.
7. Three security prohibitions with tests, plus a data inventory — every data element, why you need it, where it lives, how long you keep it, how a user gets rid of it. Rows you cannot answer are marked verify with the primary source you will read.
8. Constraints, assumptions, and dependencies as three separate tables. At least three constraints with what each rules out. At least three assumptions, each with an owner, a verify-by date, and the consequence if false. At least two dependencies, each with a pinned plan or version, a failure mode, and a fallback.
9. Obligations, with at least one verified at its primary source this week — a URL and the date you read it. Your LICENSE decision named by its SPDX identifier.
10. An out-of-scope table with at least five rows, each giving what you are not building, why not, and when it would be revisited. Start from your brief’s what-to-cut-first list.
11. The Must-hours arithmetic, in writing. Every Must estimated, summed, and compared to the thirty-hour net-feature-construction budget (hard ceiling forty). If the sum exceeds thirty, the document shows what you cut.
12. docs/traceability.csv, every requirement traced, using the columns in code/traceability.csv. Design and test columns may hold placeholders; they may not hold blanks.
13. docs/definition-of-done.md — eight to ten binary items, linked from README.md, with a note on what you cut and why.
14. docs/elicitation-notes.md — dated notes from one real conversation with one real human who has the problem, F/W/O marked.
15. Every Must identifier present as a card on your project board, titled with the identifier. docs/hours-log.csv and docs/ai-usage.md current through the end of Week 2.

The same requirement at three grades

One capability, written three ways. This is what the difference actually looks like.

A 60. Present, sincere, ungradeable.

The system should let users know about food that is going bad.

No identifier, no actor (“users” is not a persona), no condition, no priority, no verdict, no way to verify. Two engineers would build two different products from this sentence and neither could be told they were wrong.

An 80. Real work, one soft edge — and one inherited word nobody questioned.

### FR-EXP-05 — Expiry notification
**Priority:** Should
**Requirement:** The system shall notify household members about items that
are expiring soon.
**Acceptance criteria:**
- Given items are expiring, when the notification runs, then members are notified.

Identifier, priority, structure, all correct. But “expiring soon” is undefined, the criterion restates the requirement instead of testing it, there is no Adaptation: line — and the word household came from the brief and describes nobody in this student’s project. This is the most common grade in Week 2, and it is two honest questions away from the next one.

A 95. Someone else could build it, and every word in it was decided.

### FR-EXP-05 — Daily expiry notification
**Priority:** Should
**Requirement:** The system shall send one notification per kitchen per day, at
a configured time, listing every item expiring within the next three days, to
each roster member who has enabled notifications.
**Rationale:** The boathouse whiteboard went stale in four days; a daily nudge
is the smallest thing that replaces it. Most members will not open the app unaided.
**Adaptation:** Adapted — the brief addressed a household of four with a shared
calendar. A fourteen-person roster needs an opt-in rule, which the brief's
version did not have.
**Acceptance criteria:**
- Given a kitchen with items expiring in 1, 3, and 9 days and two members with
  notifications enabled, when the configured send time passes, then both members
  receive exactly one notification listing the 1-day and 3-day items.
- Given a kitchen with no items expiring within three days, when the send time
  passes, then no notification is sent.
- Given a member who has disabled notifications, when the send time passes, then
  that member receives nothing and other members are unaffected.
**Source:** Interview with the boathouse manager, 2026-09-04

Every number is a number. The empty case and the opt-out case are decided. A stranger can execute all three criteria. Nothing about the technology is stated, so Week 3 is still free to choose. And the Adaptation: line means a reviewer can see, in four seconds, that a human thought about this sentence.

Normal-tier rubric (out of 100)

Medium Tier (+ up to 25% extra credit)

Depth beyond the bar. Pick what genuinely fits your project; two done well beat four done thinly.

• A second conversation with a different kind of stakeholder — not another user like the first, but someone with a different relationship to the problem: a person who would have to operate it, pay for it, or clean up after it. Add dated notes and mark which requirements changed as a result.
• Measure three non-functional requirements 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 named for their identifiers (test_nfr_perf_01_list_p95). They fail loudly in Week 6 if you forgot them.
• Build the evaluation set this week if you have a probabilistic feature: twenty fixed cases, committed, with the pass bar written down before you build anything. Built afterward it is not an evaluation set; it is a rationalization.
• Extend the linter. Add two checks to code/check_requirements.py that catch a defect pattern specific to your domain, and include the diff and a sample report.
• A peer adaptation review. Hand your Adaptation Record and your brief to a classmate for fifteen minutes with one instruction: find the requirement I kept that I should have adapted. Record what they found and what you changed.

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

Judgment, and judgment does not delegate. Write a two-page Scope and Inheritance Memo, addressed to your instructor as if they were a client about to fund this. It must do four things an assistant cannot do for you.

1. The inheritance audit. Name the three requirements you were most tempted to keep unchanged, and say what specifically in your project made each one wrong, or defend why it was right after all. Then name the one you are least sure about, and say what would settle it. A memo claiming every inherited requirement fit perfectly is a memo written by someone who did not check.

2. The cut you have already planned. Name the two requirements most likely to be cut, ranked, each with a specific observable trigger — not “if I run out of time,” but “if the walking skeleton is not green in CI by the end of Week 3, FR-REC-02 is cut.” A cut you planned costs you a decision. A cut you did not costs you a weekend you do not have.

3. The requirement you will deliberately under-deliver on, and the defense. Pick one — usually a non-functional 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 excellence in all eight quality categories is a capstone whose author has not made a decision yet. Then name, concretely, the group of users your project will serve worst — people on old devices, low vision, metered connections, assistive technology — estimate what serving them would cost in hours, and be honest if the answer is “nothing this semester.” An honest “not this time, and here is what it would take” earns full marks. A vague claim of inclusivity earns none.

4. The integrity call. State precisely where the brief ends and you begin, and where an assistant touched this document: which prompts, which outputs you kept, which you discarded, and how you satisfied yourself that every requirement traces to a human source rather than to a template’s momentum or a model’s imagination. Then answer, in your own words: which sentence in this document would be hardest for you to defend if the user you interviewed disagreed with it, and why did you keep it?

Graded on honesty, specificity, and self-awareness. A memo reporting that everything is fine and nothing will be cut is a memo that has not been written yet.

Submission

Commit, push, and tag. The repository is the submission.

your-capstone/
├── README.md                     # links the definition of done
├── LICENSE                       # matches the obligation named in §13
├── docs/
│   ├── charter.md                # from Milestone 1
│   ├── scoping-decision.md       # from Milestone 1
│   ├── requirements.md           # THIS MILESTONE — §1-13, both halves
│   ├── elicitation-notes.md      # THIS MILESTONE — dated, F/W/O marked
│   ├── traceability.csv          # THIS MILESTONE — every FR and NFR
│   ├── definition-of-done.md     # THIS MILESTONE — 8-10 binary items
│   ├── measurements.md           # Medium tier: baselines with dates
│   ├── hours-log.csv             # current through Week 2
│   ├── ai-usage.md               # current through Week 2
│   └── scope-inheritance-memo.md # Hard tier only
└── ...

git add docs/ README.md LICENSE
git commit -m "docs: requirements specification v1.0 (Milestone 2)"
git tag milestone-2
git push --follow-tags

Your project board must show a card per Must requirement, titled with its identifier, before the tag is pushed.

Hints

• Do Rep 2 on Monday. The adaptation pass is three hours and everything else in the week gets faster once it is done. Doing it on Thursday means writing acceptance criteria for requirements you are about to withdraw.
• Renumber once, in the first hour, or never. After anything references an identifier — a board card, a branch, a test name — the freeze applies. Withdraw in place and leave the number.
• Write the acceptance criteria in the same sitting as the requirement. Coming back later doubles the time and halves the quality, because you will have forgotten why the condition was there.
• Write the measurement method before the threshold. If you cannot say how you would check it, you do not yet know what the number means. Method → condition → threshold → metric works better than the reverse for anything you are stuck on.
• When you get stuck on a sentence, ask what the failure looks like. “What happens if the list is empty, the input is bad, the network is down?” unsticks almost every requirement, because the failure case is always more concrete than the success case.
• Run the linter before you think you are done, not after — including the --stale-terms sweep. Twelve findings fixed while the document is warm take fifteen minutes; the same twelve on Sunday night take two hours.
• Do the primary-source verification early in the week. Reading a vendor’s actual terms takes longer than you expect and sometimes changes your plan, which is much cheaper to discover on Tuesday than on Sunday.
• Twelve is a floor, not a target. Twelve good requirements beat twenty-two padded ones; a reviewer who finds three unverifiable requirements starts doubting the other nineteen.
• Templates and worked examples for every artifact in this course, with the bad versions annotated, are in Appendix C. The catalog and its adaptation rules are Appendix B. The grading contract is Appendix D.

What Mastery Looks Like

A mastered specification has a specific feel to it: it is boring, it is decided, and it is owned.

Boring, because every sentence says exactly one thing and no sentence is trying to sound impressive. There is not one adjective standing on its own without a number beside it. Reading it is not exciting; executing it is trivial.

Decided, because when you look for the places a reader could take two paths, there are none — not because the author hedged, but because the author chose. Every “soon” has a number. Every “handled” has a defined behavior. Every quality has a method you could run this afternoon with tools you already have.

Owned, which is this edition’s word. Open §4 and you can see a human at work: verdicts, reasons, two withdrawals with dates on them, one requirement split because a change made it two obligations, and one line admitting that a kept requirement was kept only after the author checked. The Must list has an hours total under it, and the total fits. The out-of-scope list is long and specific and contains at least one thing the author clearly wanted to build.

That last property is the one that transfers. Every engineer you will work with can write code, and every one of them can adopt a template. The ones people trust are the ones whose written commitments hold — who say twelve things and deliver twelve, rather than inheriting forty and delivering twelve while explaining that the other twenty-eight came with the brief.

Coach’s Note — The moment that decides your grade is not a moment of writing. It is the moment you read an inherited requirement, feel the small pull to leave it alone because it is already well written, and check it anyway. Everyone reaches that moment about nine requirements in. Almost nobody stops.

When You’re Done

• docs/requirements.md exists with all thirteen sections; none is a placeholder
• 12–22 functional requirements, one consistent identifier scheme, no mixing
• Every requirement has actor, action, object, condition, priority, rationale, source, and an Adaptation: verdict
• Every Must and Should has two or more Given/When/Then criteria, one a failure case
• §4 Adaptation Record complete; every withdrawal keeps its number and carries a dated reason
• The --stale-terms sweep runs clean, or every remaining finding is justified in writing
• 8+ NFRs across 5+ categories, four fields on every one, with a sentence for each category skipped
• Three security prohibitions with tests; data inventory complete, unknown rows marked verify
• Constraints, assumptions, and dependencies in three separate tables, with owners, dates, failure modes, and fallbacks
• LICENSE present and named by SPDX identifier; one obligation verified at a primary source with a URL and a date
• MoSCoW on everything; Must hours estimated, summed, and shown against thirty
• Out-of-scope table with five or more rows, each with a reason and a revisit condition
• docs/traceability.csv covers every requirement; the checker runs clean or findings are justified
• docs/definition-of-done.md: 8–10 binary items, linked from README.md, with a note on what you cut
• docs/elicitation-notes.md committed, dated, F/W/O marked
• Somebody who has never seen the project read it and circled the ambiguities
• Must identifiers are cards on the board; docs/hours-log.csv and docs/ai-usage.md current
• Committed, tagged milestone-2, pushed, SHA submitted

A theological footnote. “Like clouds and wind without rain is a man who boasts of a gift he does not give” (Proverbs 25:14, ESV). It is a picture anyone in a dry season understands: the sky darkens, the wind picks up, everything in you leans toward the coming relief — and nothing falls. The failure is not that nothing was given. It is that something was promised, loudly, in a way that made people plan around it. An inflated requirements document does exactly that, and this edition makes inflation cheaper than it has ever been, because the promises arrive pre-written. It costs you nothing to keep a requirement. It costs you nothing to keep forty. And then Week 6 comes, and the sky is dark, and nothing falls. The verse this chapter opened with points the other way: let what you say be simply “Yes” or “No” (Matthew 5:37, ESV). Not a grander yes — a plainer one, small enough that you can keep it and specific enough that someone could tell if you did not. Twelve promised and twelve delivered. That is the whole of this milestone, and it is why §4 exists: because a word becomes yours the moment you keep it, and a promise nobody consciously made is the one nobody ends up keeping. Decide about every sentence. Then sign it, and mean it.