Chapter 2 — Reps

Twelve reps that turn an inherited draft into a specification with your name on it. These are not warmups around the milestone. They are the milestone, built one piece at a time, and if you work them in order Milestone 2 is mostly assembly by Friday.

Ground rules

• Work on YOUR project. PantryPilot, TraceLens, and CrewPantry are here to show you the shape. Every rep that says your project means the one you signed a charter for last Friday.
• Every inherited line gets a verdict. Keep, adapt, split, or withdraw — in writing, with a reason. A requirement you never explicitly decided about is a promise nobody made, and in Week 6 there will be nobody to ask why.
• Produce an artifact every time. A rep is done when a file in your repository changed and the change is committed. Not when you understand it.
• Nothing is “provisional.” Vague placeholders are how a document rots. Decide, write it down, and change it later through the change log if you were wrong.
• The assistant asks; you type. Any model use this week is questions, enumeration, or critique. Every sentence in docs/requirements.md is typed by you and logged in docs/ai-usage.md.
• Time-box each rep. If one runs past forty minutes, stop, write down where you got stuck, and move on. Stuck is information — log it in docs/hours-log.csv with a note.
• Keep the receipts. Create docs/scratch/week-02-reps.md and paste each rep’s output into it as you go. Half of it becomes the milestone.

Block A — Inherit, interrogate, and decide

Rep 1 — The identifier scheme, settled in one hour

Before anything else, freeze the shape of your identifier space. List your feature areas — three to six of them, not eight, because you are building three to four Must features — and give each a three-or-four-letter code.

AREA CODE   AREA NAME       ONE SENTENCE OF SCOPE
INV         Inventory       Everything about items in the kitchen
EXP         Expiry          Everything about dates and warnings
ACC         Accounts        Sign-in, the roster, recovery

Then restate your brief’s requirement identifiers in your scheme — all of them, now, before anything references them — and write the rule at the top of the document in one sentence: identifiers are FR-<AREA>-<nn>, assigned once, never reused, never renumbered.

Reflect: How many areas did you end up with? More than six in an eight-week course usually means you are still carrying something Week 1 should have cut.

Rep 2 — The adaptation pass

The big one. Open code/adaptation-worksheet.md and run all three questions on every requirement your brief handed you: does my actor appear in it, does my scope still contain it, does the acceptance data exist in my project. Then assign one of four verdicts — keep, adapt, split, withdraw — and write the reason in the same sitting.

Budget three hours for ten to fourteen inherited requirements. The finished table becomes §4 of docs/requirements.md.

Reflect: Which requirement did you keep that you were tempted to keep without reading? Name it. That is the one that would have cost you a weekend in Week 6.

Rep 3 — The stale-noun sweep

List the nouns that belong to the brief and not to your project — household, barcode, administrator, tenant, subscription. Then run the sweep over the provided worked document first, so you know what a clean report looks like, and then over your own:

python3 check_requirements.py code/srs-template.md --stale-terms household,barcode,admin
python3 check_requirements.py docs/requirements.md --stale-terms <your list>

Use code/check_requirements.py. Fix every ERROR: adapt the sentence, or withdraw it and leave the number in place.

Reflect: Report two numbers honestly — how many stale terms you had already caught in Rep 2, and how many the sweep found that you had not. The second number is the one that predicts your Week-4 review.

Rep 4 — Thirty minutes with a real human

Find one person who actually has the problem your project solves. Not a classmate being polite about your idea. Thirty minutes, and one question does most of the work: “walk me through the last time you did this.” Not “what do you need,” which produces a wish list. Not “would you use an app that…,” which produces politeness.

Within an hour, transcribe your notes into docs/elicitation-notes.md, dated, marking every sentence F (a fact about today), W (a want), or O (an opinion).

Reflect: Name three things you believed before the conversation that you no longer believe. If the answer is “nothing changed,” you asked leading questions — the brief had already told you the answers and you went looking for agreement.

Rep 5 — Personas with evidence, not archetypes

Two or three personas. Four fields each: who they are in one sentence, what they need in one sentence, one behavior that constrains your design, and — the graded one — the evidence they exist. An interview date. An observation. A photograph of the thing they use today.

One persona must be the next maintainer, the person who clones this repository knowing nothing.

Reflect: Which persona’s evidence line says “from the brief”? Fix it or delete the persona. A brief gives you an archetype; only Rep 4 gives you evidence.

Block B — Write what the brief could not give you

Rep 6 — Four requirements that are yours alone

Your project differs from the brief in ways the brief could not anticipate. Write four new functional requirements that exist only because of those differences, in the full six-part shape from code/srs-template.md: identifier, actor, action, object, condition, priority — plus a rationale line, a Source: line, and Adaptation: New.

### FR-<AREA>-<nn> — <short imperative name>
**Priority:** Must | Should | Could | Won't
**Requirement:** <Actor> shall be able to <action> <object> <condition>.
**Rationale:** <which persona, and why>
**Adaptation:** New — <what about my project produced this>

Reflect: Which of the four forced a decision you had been avoiding? Write the decision in one sentence. You just made a design choice for free, a week before it would have cost you code.

Rep 7 — Acceptance criteria, two per requirement

Every Must and Should gets at least two Given/When/Then criteria: one happy path, one thing going wrong. Numbers everywhere — no “soon,” no “several,” no “large.”

- Given <specific starting state with specific data>, when <actor does X>,
  then <observable result>.
- Given <the failure case>, when <trigger>, then <defined behavior>.

Then run the inheritance test on every inherited criterion: does it name data, a role, or an integration that exists in your project? “Given two household members” in a single-user project is not a weak criterion. It is somebody else’s criterion.

Reflect: Apply the stranger test to your weakest criterion. Could someone with no access to your code run it and get an unambiguous pass or fail? If not, what is missing — the starting data, the trigger, or the observable result?

Rep 8 — The Requirement Adapter, then your own worst five

Do the on-page Requirement Adapter widget end to end and record two numbers: your verdict accuracy, and the item where your running Must-hours total first crossed thirty.

Then turn the drill on yourself. Find the five worst sentences in your own draft, tag each with every defect from the palette — ambiguous, unverifiable, compound, solution-biased, missing actor, missing condition, unmeasurable, inherited — and rewrite it.

| # | My original sentence | Defects tagged | Rewritten |
|---|----------------------|----------------|-----------|

Reflect: Which defect did you commit most often? Everyone has a signature defect, and knowing yours is worth more than knowing all eight, because you can watch for it in real time.

Rep 9 — Eight non-functional requirements in ninety minutes

Five categories minimum, four fields each — metric, threshold, condition, method. Your brief handed you targets with numbers in them; it did not hand you the condition or the method, and those two fields are what make a requirement real.

| ID | Metric | Threshold | Condition | Measurement method | Priority |

Rules: the threshold is a number with a unit. The condition names the data volume, the network, and the device or environment. The method is something you could run this afternoon with tools you already have. For every category you skipped, write one sentence saying why it does not apply — “not applicable” alone earns nothing.

Reflect: Which adjective was hardest to convert, and what did that difficulty tell you about how well you actually understand your own system?

Rep 10 — Prohibitions, the data inventory, and one verified obligation

Three artifacts, ninety minutes, and they are the ones that get skipped.

1. Three security prohibitions, each with a test: no credential in the repository at any commit; every write authorized server-side; all persistence through parameterized queries or the framework’s query builder.
2. The data inventory — every element you touch, why you need it, where it lives, how long you keep it, and how a user gets rid of it. Mark the rows you cannot answer from your own knowledge as verify.
3. One obligation verified at its primary source, this week. A license, an API’s terms, a dataset’s terms. Write the URL and the date you read it. Not what you assumed, and not what a model told you.

Reflect: Which row of the data inventory did you not want to fill in? Fill it in. That reluctance is the most reliable signal in this rep.

Block C — Prioritize, trace, and commit

Rep 11 — MoSCoW and the hour arithmetic

Assign Must, Should, Could, or Won’t to every requirement. Then run both checks. The ratio check: Musts at no more than about half your total. The hours check, which is this edition’s: estimate every Must in hours including tests and failure paths, sum it, and compare to thirty — the honest net-feature-construction budget in a 160-hour course, with a hard ceiling of forty you can only reach by borrowing from testing and documentation.

Over thirty? Cut now, while cutting costs one line in a change log. Then build the out-of-scope table: five rows minimum, each with what you are not building, why not, and when it would be revisited. Your brief’s what-to-cut-first list is the first three rows.

Reflect: Which Won’t row hurt to write? One sentence on why you wanted it, one on what it would have cost in hours. That pair is the beginning of the Hard-tier memo.

Rep 12 — The matrix, the linter, and the definition of done

Build docs/traceability.csv from the columns in code/traceability.csv — one row per requirement, design and test columns holding placeholders this week. Run the checker over the provided file first; it is deliberately broken in three places, and you should be able to name all three before you run it:

python3 check_requirements.py code/traceability.csv
python3 check_requirements.py docs/traceability.csv

Then adopt a definition of done: eight to ten items, every one answerable yes or no by someone who is not you, linked from README.md. Cut anything you will not do every single time, and write one line saying what you cut and why. 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.

Reflect: How many items did you cut from the starting list, and which one did you cut because you knew you would skip it in Week 5? Naming it now is worth more than pretending.

Done? One Last Thing.

The stranger read, in twenty minutes. The whole point of this document is that somebody who is not you can act on it. Test that before you submit, not after.

1. Hand docs/requirements.md to one person who has never heard about your project. A roommate, a classmate in another section, a family member. Not your instructor.
2. Give them a pen and exactly two instructions: “Circle every sentence where you could imagine two different programs both satisfying it,” and “underline anything that sounds like it belongs to a different project than the one I just described in one sentence.”
3. Sit there. Do not explain. Do not defend. The urge to say “well, what I meant was…” is the entire lesson — every time you feel it, you have found an ambiguity, because the reader will not be sitting next to you in Week 6.
4. Fix every circle and every underline. Some fixes are a number, some are a split, some are a definition added to §3, and some are a withdrawal you should have made on Monday.
5. Add one row to the §9 change log: the date, “ambiguity and inheritance pass after external read,” and how many sentences changed.
6. Commit with a message your reviewer can follow: docs: requirements v1.0 after external read (Milestone 2).

Fewer than three circles means they were being polite or you handed them the wrong document. Fifteen is not a failure — that is fifteen defects caught in Week 2 for the price of twenty minutes, instead of in Week 6 for the price of a feature you do not have the hours to rebuild.

Up next: Milestone 2