Chapter 4 — Reps

Twelve reps that turn adjectives into numbers, notes into three separate tables, and a pile of promises into a matrix. Every one of them produces something you will paste into Milestone 4 an hour from now.

Ground rules

• Work on your own project. The drills use PantryPilot and TraceLens as worked examples, but every rep that says your project means yours. Generic answers earn generic grades.
• Four fields or it doesn’t count. Metric, threshold, condition, method. A rep that produces a requirement missing one of the four is not finished.
• No claim without a source. Any statement about a license, a vendor’s terms, a price, or a limit gets a URL and the date you checked it. That includes claims an assistant handed you.
• Time-box each rep. If a rep runs past 40 minutes, stop, write down where you got stuck, and move on. Stuck is information — log it in your hours log with a note.
• Commit as you go. These reps produce document sections. Small commits with real messages; your commit history is graded in Week 16.
• Keep the receipts. Create a scratch file in your repository — docs/scratch/week-04-reps.md is fine — and paste each rep’s output into it. Half of it becomes the milestone.

Block A — Making a quality measurable

Rep 1 — Five adjectives, four fields

Open your Week-3 requirements document and your project charter. Write down five adjectives you have used anywhere about your system: fast, simple, secure, reliable, clean, intuitive, lightweight, scalable — whatever you actually wrote.

Now force every one through the grid. Produce a table with these columns and no blanks:

| Adjective | Metric | Threshold | Condition | Measurement method |

Rules: the threshold must be a number with a unit. The condition must name the data volume, the network, and the device or environment. The method must be something you could run this afternoon.

Write: two or three sentences on the adjective that was hardest to convert, and what that difficulty told you about how well you understand your own system.

Rep 2 — The percentile drill

Twenty timed page loads, in seconds:

0.38  0.41  0.39  0.44  0.40  0.42  0.37  0.45  0.41  0.39
0.43  0.40  0.38  0.46  0.42  0.41  0.39  0.44  2.90  9.20

Compute three numbers by hand or with one line of code: the mean, the p95 using the nearest-rank method (sort ascending, take the value at position ceil(0.95 × n)), and the max.

You should get a mean of about 0.97 s, a p95 of 2.90 s, and a max of 9.20 s.

Write: which of the three numbers you would put in a requirement, and why. Then answer this: if your requirement said “average page load under 1.5 seconds,” would this system pass? Would your users agree?

One more thing to notice, and it matters for your document: percentile has more than one definition — nearest-rank and interpolated methods give different answers on small samples. That is exactly why the method field exists. Write down which one you used.

Rep 3 — Diagnose and rewrite

Here are six requirements from a capstone document. Every one of them is real in shape and useless in practice.

NFR-1  The application should have good performance.
NFR-2  The system must be highly available and scalable.
NFR-3  The UI shall be intuitive.
NFR-4  User data will be kept safe.
NFR-5  The code should follow best practices.
NFR-6  The app should work on mobile.

For each, do two things. First, tag every defect from this palette: unmeasurable · missing condition · compound (two or more requirements in one) · solution-biased · aspirational, not verifiable · enterprise target copied to a student project · no measurement method. Most of these carry two or three tags.

Second, rewrite it with an identifier, a priority, the four fields, and a measurement method — as if it were your own project. A compound requirement must become two or three separate ones; do not fix it by making the sentence longer.

Write: which of the six you found hardest to rewrite, and whether the difficulty was in the metric, the threshold, the condition, or the method.

Block B — The categories that get skipped

Rep 4 — The data inventory

Build the table from section 4.4 for your project. One row per data element you touch — including things you would not have called data: email addresses, uploaded files, session logs, error reports, anything you send to a third party.

| Data element | Why you need it | Where it lives | How long you keep it | How a user gets rid of it |

Two columns will defeat you: retention and deletion. That is the point.

Write: name the two rows where you genuinely do not know the answer. For each, name the primary source you would read to find out — a vendor’s terms page, your hosting provider’s docs — and put it on your Week-5 list. Do not guess. Do not ask a chatbot and write down what it says.

Rep 5 — The mouse-unplugged pass

If you have any prototype, wireframe, or even a static HTML page: unplug your mouse or trackpad, or put your hand in your lap and do not touch it. Complete your project’s three core tasks using only Tab, Shift+Tab, Enter, Space, and the arrow keys.

If you have no interface yet, do this on any web application you use daily — your school’s portal, your bank, your email — and take the same notes. You are training the eye, not the app.

If your project is a CLI, do the equivalent: run your tool (or a tool you admire) with color disabled and with output piped to a file. Can you still tell an error from a warning? Does --help read aloud sensibly? Does the exit code mean anything?

Write down every place you got stuck, could not tell where focus was, or could not reach a control.

Write: turn at least three of your stuck points into properly formed NFRs with identifiers and measurement methods. These go straight into the milestone.

Rep 6 — Contrast and grayscale

Two ninety-second tests, both of which will surprise you.

1. Take every text-on-background color pair in your design — or in your terminal theme — and run it through a contrast checker. Record the ratios. Anything below 4.5:1 for body text fails WCAG Level AA.
2. Set your display to grayscale (every major desktop OS has an accessibility setting for this) and complete your three core tasks. Anything you can no longer distinguish was being communicated by color alone.

Write: the failing pairs, what you will change, and one requirement that locks the fix in place so it does not regress in Week 12 when you restyle everything.

Rep 7 — The prohibitions, and the history check

Write your five security requirements as prohibitions — things that must never be true — using the starter set in section 4.4 as a menu, not a script. Each needs a measurement method.

Then run the check on your actual repository. Search your full history, not just the working tree:

git log --all -p | grep -inE "api[_-]?key|secret|password|token|BEGIN [A-Z ]*PRIVATE KEY" | head -40

That is a crude filter and it will produce false positives — the point is to look. If you find a real secret, understand what you are dealing with: it is in the history, and deleting it in a new commit does not remove it. Rotate the credential first, then deal with the history.

Write: what you found (or that you found nothing), and the one line you are adding to your definition of done so this cannot happen again.

Block C — Constraints, assumptions, and obligations

Rep 8 — Sort the pile

Here are twelve items from a real student’s “notes” section. Sort each into constraint, assumption, or dependency. Some are trickier than they look.

a. The course ends in Week 16.
b. The barcode API's free tier allows 1,000 calls per day.
c. I have no administrator rights on my laptop.
d. The hosting provider will still have a free tier in December.
e. The app needs a hosted database.
f. I can only work about 15 hours a week.
g. My roommates will test the app in Week 11.
h. The charting library I want to use is GPL-licensed.
i. CI minutes on my provider's free plan.
j. I must demo live in a 30-minute session.
k. Two hundred pantry items is a realistic maximum for one household.
l. The framework's auth module handles password hashing for me.

Sort them all before you read on.

Answer key. Constraints: a, c, f, j — you did not choose them and cannot change them. Assumptions: b, d, g, k, l — every one could turn out false, and each needs an owner and a verify-by date. Dependencies: e, i — outside your control, needing a pinned plan, a failure mode, and a fallback.

Two of them deserve an argument. (h) is a dependency and an obligation: you depend on the library, and its license imposes conditions on how you may distribute what you build with it. Put it in both tables. (l) is an assumption right now and becomes a dependency the moment you verify it in the docs — which is a good picture of how assumptions are supposed to die.

Write: now build all three tables for your own project — at least four constraints, four assumptions with owners and verify-by dates, and three dependencies with failure modes and fallbacks. Use code/nfr-template.md.

Rep 9 — Verify one obligation at the source

Pick the single obligation that would hurt most if you were wrong about it. Candidates: the license of a library you plan to build on, the terms of the API you plan to call, or the storage/caching rules of a data source.

Go to the primary source. Not a blog post. Not a summary. Not a chatbot. The dependency’s own LICENSE file, the vendor’s own terms page, the dataset’s own page.

Record a row in your obligations table: the obligation, the URL, the date you checked, and one sentence on what it requires of you.

Write: did the primary source say what you expected? Name one thing you learned that you would not have guessed. If it said exactly what you expected, say so plainly — that is a real result too.

Rep 10 — The enumeration pass, and the cull

Use the prompt from section 4.10 with an assistant. Paste your functional requirements and your charter; ask for the non-functional requirements and obligations you have missed.

Then do the work that makes it yours:

1. Cull. Delete everything that does not apply to your project. Expect to delete half or more. Over-scoping is the assistant’s most reliable failure here.
2. Rewrite. Every survivor gets your identifier scheme, your priority, and a measurement method you can actually run. Generated measurement methods are frequently impossible at student scale.
3. Flag. Mark every claim about a license, a regulation, a price, or a vendor limit. Verify each at the primary source or delete it.

Write: a short honest note — how many it proposed, how many you kept, and at least one thing it got wrong. Name the wrong thing specifically. If you claim it got nothing wrong, you did not check the claims. This note goes in docs/ai-usage.md as part of your disclosure.

Block D — Traceability and done

Rep 11 — Break it, then fix it

Get code/traceability-matrix.csv and code/check-traceability.py into the same directory, then run:

python3 check-traceability.py traceability-matrix.csv

You will get eight findings across five kinds. For each finding, write one sentence saying what a project manager should do about it — not what the script says, what a person should do. “Demote FR-005 to Could and record the decision” is an answer. “Add a design element” is not, unless you say which one.

Then fix the file so the script exits clean, and run it once more to prove it.

Now build your matrix from your Week-3 functional requirements plus this week’s non-functional ones, and run the checker on it. Placeholders in the design and test columns are fine this week — blanks are not.

Write: how many orphans you had on the first run, and whether any of them were requirements you had quietly stopped intending to build.

Rep 12 — Write it, then cut it

Copy code/definition-of-done.md. Add anything your project specifically needs — a migration step, a data-seeding step, a screenshot in the changelog.

Then do the harder half. Go item by item and ask: will I do this at 11 p.m. on a Tuesday in Week 12, when the feature works and I want to sleep? If the honest answer is no, delete the item. Not “keep it as an aspiration.” Delete it.

Land between eight and twelve items you will genuinely honor.

Write: which items you cut and why. Then a harder sentence: name the one item you kept that you are least sure you will honor, and say what you will change about your workflow to make it survive Week 12.

Done? One Last Thing.

Assemble the NFR one-pager — a single page you could hand to a reviewer who has ten minutes and no patience. It contains, in this order:

1. Your three most important non-functional requirements, each with all four fields and its measurement method.
2. The one constraint that shapes your design more than any other, and one sentence on what it rules out.
3. The one assumption that would cost you the most if it were false, with its owner, its verify-by date, and what you will do if it fails.
4. The one obligation you verified at a primary source this week, with the URL and the date.
5. Your definition of done, in full.
6. A traceability summary line: how many requirements, how many traced to a design element, how many traced to a test, how many orphans remain and why.

Then read the whole page aloud, slowly. Every time you hear an adjective without a number, stop and fix it before you move on. Reading aloud catches vagueness that reading silently does not — your ear is less forgiving than your eye.

That one page is the spine of Milestone 4. If it is honest, the milestone is mostly assembly.

Up next: Milestone 4