Milestone 3 — Software Requirements Specification v1

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

Chapter: Chapter 3 — Requirements: Saying Exactly What You Will Build Week: 3 of 16 · SDLC phase: Requirements · Hat: business analyst Due: End of Week 3, before the Week-4 session Submit: Committed and pushed to your capstone repository, tagged milestone-3. Nothing is emailed and nothing is uploaded; the repository is the submission for every milestone in this course. Where it lands in the final package: docs/requirements.md — the single most-referenced document in your repository. It feeds the Week-16 rubric’s requirements specification line directly, and indirectly feeds technical specification, test suite and results, and scope defended in the presentation. Chapter 4 appends non-functional requirements to the same file. Chapter 6 answers it. Chapter 11 tests it. AI policy: Open, with one hard line. An assistant may ask you questions, enumerate cases you missed, and attack a sentence for ambiguity. It may not author a requirement. Every sentence in the document is typed by you. Log every substantive use in docs/ai-usage.md — tool, what you asked, what you kept, what you discarded and why. A generated requirement with no human source is an integrity problem, not a style problem, and it is treated as one.

The Setup

You have one project idea and a scoping memo. Right now that idea lives almost entirely inside your head, which feels fine, because your head has been a reliable place to keep things for the last three years of coursework.

It will not be reliable for this. In Week 12 you will have written four thousand lines of code, changed your mind twice, lost a weekend to an integration you did not expect, and completely forgotten what you meant in Week 3 by “the app reminds you about things.” Your Week-3 self is the only person who can protect your Week-12 self, and the only tool they have is a document.

So write it as if you were handing the project to a competent engineer you will never speak to. Because in a real sense, you are: that engineer is you, four months from now, tired, with the deadline visible. They will not remember the conversation you are having with yourself today. They will only have what you wrote down.

That is the standard this milestone is graded against. Not “is it thorough.” Could somebody else build this and hand you back the thing you meant?

Learning Targets

You will demonstrate that you can:

• Elicit requirements from a real stakeholder using a structured technique, and record the evidence.
• 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.
• Prioritize honestly with MoSCoW, including the discipline of writing down what you will not build.
• Identify and repair the seven classic requirement defects in your own writing, not just in examples.
• Specify a probabilistic feature, if your project has one, by its envelope, guardrails, fallback, and fixed evaluation set.
• 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 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

The bar. This is what a complete, professional requirements specification looks like at capstone scale.

Required deliverables

1. docs/requirements.md, built from the provided template in code/srs-template.md, with all nine sections present. Section 6 (non-functional) is the one legitimate placeholder — Chapter 4 fills it.
2. Eighteen to thirty-five functional requirements. Below eighteen, a 240-hour project is almost certainly under-specified; above thirty-five, you are specifying at a level of detail that belongs in the technical specification. If your project genuinely falls outside the band, say so in section 1 and defend it in two sentences.
3. Every requirement carries all six parts — identifier in FR-<AREA>-<nn> form, actor, action, object, condition, priority — plus a rationale line and a source line.
4. Every Must and Should requirement carries at least two acceptance criteria in Given/When/Then form: one happy path, one thing going wrong.
5. Two to three personas, each naming the evidence it came from, and each traceable to at least one requirement. One of them is the next maintainer.
6. MoSCoW on every requirement, with Musts at roughly half your total or below.
7. 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.
8. docs/elicitation-notes.md — dated notes from one real conversation with one real human who has the problem, marked F/W/O.
9. Every Must identifier present as a card on your project board, titled with the identifier.
10. docs/hours-log.csv and docs/ai-usage.md current through the end of Week 3.

The same requirement at three grades

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

A 60. Present, sincere, ungradeable.

The system should let users know about expiring food.

No identifier, no actor (“users” is not a persona), no condition (how soon is expiring?), no priority, 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.

### 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, actor, structure — all correct. But “expiring soon” is still undefined, and the criterion restates the requirement instead of testing it. This is the most common grade in Week 3, and it is one honest question away from the next one.

A 95. Someone else could build it.

### FR-EXP-05 — Daily expiry notification
**Priority:** Should
**Requirement:** The system shall send one notification per household per day,
at a household-configured time, listing every item expiring within the next
three days, to each member who has enabled notifications.
**Rationale:** Dana's whiteboard went stale in four days; a daily nudge is the
smallest thing that replaces it. Marcus will not open the app unaided.
**Acceptance criteria:**
- Given a household 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 household 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 Dana, 2026-02-03; interview with Marcus, 2026-02-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 5 is still free to choose.

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 elicitation session 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 the notes, dated, and mark which requirements changed as a result.
• An observation pass. Twenty minutes watching someone do the task without helping, using the observation table in code/elicitation-interview-guide.md. Report at least two requirements that came from something you saw and nobody said.
• A data dictionary in section 3: every entity your requirements mention, with its fields, types, and the rule that governs each. This is a substantial head start on Week 6.
• A requirements walkthrough with a peer, structured: they read the document cold and mark ambiguities, you record every mark in a change table with what you did about it, and you write two sentences on the one comment you rejected and why.
• 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.
• Low-fidelity sketches — hand-drawn is fine, photographed is fine — with each sketch region labeled by the identifier it satisfies. Sketches with no identifiers earn nothing; the point is the traceability, not the drawing.

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

Judgment. This tier is deliberately something an assistant cannot produce for you, because it requires you to be accountable for a decision, and accountability is the one thing a tool cannot supply.

Write a two-page Scope Defense Memo, addressed to your instructor as if they were a client who is about to fund this, containing all four of these:

1. The three requirements most likely to be cut, ranked, with the trigger for each. Not “if I run out of time” — a specific, observable trigger: “if the walking skeleton is not integrated by the end of Week 9, FR-SCAN-01 is cut.” A cut you have already planned is a cut that costs you a decision, not a weekend.
2. The one requirement you are least confident anyone actually wants, named, plus the cheapest experiment that would tell you within a week. Then say what you will do with each possible answer. A test you would ignore the result of is not a test.
3. A defense of one Won’t-have that a reasonable reader would call a Must. Pick the item on your out-of-scope list that a skeptic would push back hardest on, state their argument fairly and at its strongest, and then answer it with your reasoning and your hour arithmetic. If you cannot state their case fairly, you have not understood your own decision.
4. The integrity call. State precisely where an assistant touched this specification: which prompts, which outputs you kept, which you discarded, and how you satisfied yourself that every requirement in the document traces to a human source rather than to a model’s imagination. Then answer, in your own words, this question: which sentence in this document would be hardest for you to defend if a user disagreed with it, and why did you keep it?

Graded on honesty, specificity, and self-awareness. A memo that says everything is going 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                     # updated: one line on what the project is
├── docs/
│   ├── charter.md                # from Milestone 1
│   ├── scoping-decision.md       # from Milestone 2
│   ├── requirements.md           # THIS MILESTONE — sections 1-9
│   ├── elicitation-notes.md      # THIS MILESTONE — dated, F/W/O marked
│   ├── hours-log.csv             # current through Week 3
│   ├── ai-usage.md               # current through Week 3
│   └── scope-defense-memo.md     # Hard tier only
└── ...

git add docs/
git commit -m "docs: requirements specification v1.0 (Milestone 3)"
git tag milestone-3
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 3 first, on day one. Every other rep gets faster once you have talked to a real person, and every hour you delay the interview is an hour of requirements written out of your own assumptions.
• Write the acceptance criteria immediately after the requirement, in the same sitting. Coming back to them later doubles the time and halves the quality, because you will have forgotten why the condition was there.
• 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. Fixing twelve errors while the document is warm takes fifteen minutes; fixing them the night it is due takes two hours.
• Read code/pantrypilot-requirements-sample.md once, early. Not to copy — to calibrate. Most students under-specify because they have never seen the finished shape.
• If you have an AI feature, do section 3.9 of the chapter properly. Build the fixed evaluation set this week, before you build the feature. Building it afterward is not an evaluation set; it is a rationalization.
• Do not write non-functional requirements yet. Leave section 6 empty. Every year somebody spends four hours writing “the system shall be secure” and has to delete it in Week 4.
• Templates and worked examples for every artifact in this course, including the bad versions annotated, are in Appendix B. The grading contract is in Appendix C.

What Mastery Looks Like

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

Boring, because every sentence says exactly one thing and no sentence is trying to sound impressive. There is no adjective doing work that a number should be doing. 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 “handle” has a defined behavior. Every “users” has a persona. The document does not defer anything to the reader’s good judgment, because the reader will not be there.

And it is honest. The out-of-scope list is long and specific. The open questions section admits real gaps with names and dates against them. The Musts are a number one person could plausibly build in four weeks. Nothing in it is promised that the author does not intend to deliver.

That last property is the one that transfers. Every engineer you will work with can write code. The ones people trust are the ones whose written commitments hold — who say twelve things and deliver twelve, rather than saying forty and delivering twelve while explaining that the other twenty-eight were aspirational.

Coach’s Note — You are going to be tempted to leave three or four sentences slightly vague, because pinning them down means making a decision you do not feel qualified to make yet. Make it anyway, and write it down. A wrong decision recorded in Week 3 costs you one change-log row in Week 8. A decision deferred costs you a week in Week 12, when there is nothing left to spend.

When You’re Done

• docs/requirements.md exists with all nine sections; only section 6 is a placeholder
• 18–35 functional requirements, each with a unique FR-<AREA>-<nn> identifier
• Every requirement has actor, action, object, condition, priority, rationale, and source
• Every Must and Should has at least two Given/When/Then criteria, one of them a failure case
• 2–3 personas, each with its evidence named; one is the next maintainer
• MoSCoW applied to everything; Musts at roughly half or below
• Out-of-scope table with five or more rows, each with a reason and a revisit condition
• docs/elicitation-notes.md committed, dated, F/W/O marked
• The linter reports zero errors, and every warning was decided rather than ignored
• Somebody who has never seen the project read it and circled the ambiguities (the stranger read that closes the reps)
• Must identifiers are cards on the board; docs/hours-log.csv and docs/ai-usage.md are current
• Committed, tagged milestone-3, pushed

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. That is what an inflated requirements document does. Forty features announced, twelve delivered, and a presentation in Week 16 that spends its first five minutes explaining the weather. 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 — a promise small enough and clear enough that you can actually keep it, and specific enough that someone could tell if you did not. That is the whole of this milestone. Say fewer things. Say them exactly. Then go be the kind of engineer whose documents can be trusted, which is, in the end, the same thing as being the kind of person whose word can be.