Chapter 3 — Reps

These are not warmups around the milestone. They are the milestone, built one piece at a time. Work them in order and by Rep 12 the specification exists.

Ground rules

• Work on YOUR project. Every rep operates on the idea you kept in Week 2. PantryPilot and TraceLens are here to show you the shape; they are not the assignment.
• Produce an artifact every time. A rep is not done when you understand it. It is done when a file in your repository changed and the change is committed.
• Nothing is “provisional.” Vague placeholders in a specification 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 write. 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.
• Log your hours as you go, not at the end of the week from memory. Week 7’s estimating work is only as good as this week’s data.
• Write the reflection. Two to four sentences of plain prose. A rep without its reflection is half a rep.

Block A — Finding out what you are actually building

Rep 1 — Feature areas and the identifier scheme

Before a single requirement gets written, decide the shape of your identifier space. List every feature area your system has — four to seven of them — and give each a three-or-four-letter code.

AREA CODE   AREA NAME              ONE SENTENCE OF SCOPE
INV         Inventory              Everything about items in the pantry
EXP         Expiry                 Everything about dates and warnings
SCAN        Barcode                Adding items without typing
REC         Recipes                Suggestions from what is on hand
ACC         Accounts               Sign-in, households, recovery

Then write the rule at the top of your requirements document in one sentence: identifiers are FR-<AREA>-<nn>, assigned once, never reused, never renumbered.

Reflect: How many areas did you end up with? Fewer than four usually means the project is too small to defend; more than eight usually means you are still carrying something Week 2 should have cut.

Rep 2 — The persona set, with evidence

Write two or three personas. Each gets four fields: who they are in one sentence, what they need from the system in one sentence, one behavior that constrains your design, and — the graded one — the evidence they exist.

| Persona | Who | Needs | Constraining behavior | Evidence |
|---------|-----|-------|-----------------------|----------|

One of your personas must be the next maintainer — the person who clones the repository knowing nothing about it.

Reflect: Which persona has the weakest evidence line? Be honest. If the honest answer is “I made them up,” that is Rep 3’s job, and you should do Rep 3 today.

Rep 3 — The elicitation interview

Find one human being who has the problem your project solves. Not a classmate being polite about your idea — someone who actually experiences the thing. Run the eight-question script in code/elicitation-interview-guide.md for thirty minutes.

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

Reflect: Name three things you believed before the interview that you no longer believe. If the answer is “nothing changed,” you asked leading questions — reread the “questions to avoid” table and try again with a different person.

Rep 4 — Twenty questions nobody answered

An assistant is genuinely good at this. Give it one paragraph describing your project and use the INTERROGATE prompt from section 3.8: twenty questions, one at a time, whose answers it would need before it could write a requirement — and no requirements.

Answer all twenty in writing, in your own words. Any you cannot answer becomes a row in section 8, Open Questions, with a name and a date next to it.

Reflect: How many of the twenty could you not answer? That count is your real ambiguity level going into this week. Which single unanswered question would do the most damage if you got it wrong?

Block B — Turning what you learned into requirements

Rep 5 — Ten user stories, INVEST-screened

Write ten stories in the canonical form, using your interviewee’s words for the capability. Then screen each against INVEST and mark which letter it fails.

As a <persona from Rep 2>, I want <capability, in their words>,
so that <benefit that matters to them>.
INVEST:  I_ N_ V_ E_ S_ T_        Fails: ____

Reflect: Which letter did you fail most often? Almost everyone fails T (testable) first, and almost everyone fails it for the same reason: a word in the story has no definition yet. Name that word.

Rep 6 — Eight stories become eight requirements

Take eight of the stories from Rep 5 and convert each into a six-part requirement: identifier, actor, action, object, condition, priority. Use the block shape from code/srs-template.md.

### 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>
**Source:** <interview date, observation, or your own recorded decision>

Reflect: Which requirement forced you to make a decision you had been avoiding? Write the decision down in one sentence. That sentence is a design decision you got for free, four weeks before you would have had to make it in code.

Rep 7 — Acceptance criteria, two per requirement

Every Must and Should requirement from Rep 6 gets at least two Given/When/Then criteria: one happy path and 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>.

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 specifically is missing — the starting data, the trigger, or the observable result?

Rep 8 — The rewrite drill

Do the on-page Requirement Rewriter widget end to end and record your tagging score. Then turn the drill on yourself: find the five worst sentences in your own draft, tag each with every defect from the palette, and rewrite it.

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

Reflect: Which defect did you commit most often in your own writing? Everyone has a signature defect. Knowing yours is worth more than knowing all seven, because you can watch for it.

Block C — Priority, honesty, and the document

Rep 9 — MoSCoW triage and the Won’t-have list

Assign Must, Should, Could, or Won’t to every requirement you have. Then count them. If Musts are more than about half your total, you have not prioritized — sort the Musts against each other and demote the bottom third.

Then build the Won’t-have table: at least five rows, each with what you are not building, why not, and when it would be revisited.

Reflect: Which Won’t row hurt to write? Write one sentence about why you wanted it and one sentence about what it would have cost. That pair is the beginning of the scope-defense memo in the Hard tier.

Rep 10 — Run the linter

Assemble everything into docs/requirements.md using the template, then run:

python3 check_requirements.py docs/requirements.md

Use code/check_requirements.py. Run it against code/pantrypilot-requirements-sample.md first so you know what a clean report looks like. Then fix every ERROR in your own file. Warnings are judgment calls; decide each one deliberately rather than ignoring the lot.

Reflect: How many errors did it find on the first pass? Which one surprised you? A tool that finds nothing on your first draft usually means the tool is not being pointed at the whole file.

Rep 11 — The AI audit

Use the FIND THE HOLES prompt from section 3.8 on your finished requirement set: situations a user could get into that no requirement covers, each named against the identifier that should have covered it.

Then audit the exchange. In docs/ai-usage.md, log four things: what you asked, what came back, what you kept, and what you discarded and why.

Reflect: How many genuinely uncovered situations did it find, and how many were invented? Report both numbers honestly. The ratio is the most useful thing you will learn about this tool all semester.

Rep 12 — Wire the identifiers to the board

Every Must requirement becomes a card on your project board, titled with its identifier — FR-INV-01 Add a pantry item. Nothing else changes; do not estimate yet, that is Week 7.

Reflect: Look at the board. Does the number of Must cards look like something one person can build in the Week 9–12 construction window? Write down your gut number of hours. You will check it against reality in Week 7, and the gap will teach you more than the estimate did.

Done? One Last Thing.

The stranger read. 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. Print or export docs/requirements.md and hand it 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 one instruction: “Circle every sentence where you could imagine two different programs both satisfying it.”
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 have you sitting next to them in Week 12.
4. Fix every circle. Some fixes are a number; some are a split; some are a definition added to section 3.
5. Add one row to the section 9 change log: the date, “ambiguity pass after external read,” and how many sentences changed.
6. Commit with a message your grader can follow: docs: requirements v1.0 after external ambiguity read.

If they circled fewer than three sentences, they were being polite or you handed them the wrong document. If they circled fifteen, that is not a failure — that is fifteen defects caught in Week 3 for the price of twenty minutes, instead of in Week 12 for the price of a feature.

Up next: Milestone 3