Chapter 8 — Reps: The Design Review Lab

There is no Milestone 8. These twelve reps are this week’s graded work — the full design review, from assembling the package to declaring the baseline to auditing your own pace at the halfway mark. Work them in order; each one feeds the next.

Ground rules

• Everything lands in the repository. Nothing here counts if it lives in a notebook, a chat thread, or your head. New this week: docs/review/ and docs/change-requests/.
• Log your hours as you go, in the same docs/hours-log.csv you started in Week 1, category review. Rep 12 reads that file. Backfilling it on Sunday defeats the only measurement instrument you have.
• Every finding gets a location. Document, section, and — where it applies — a requirement id. A finding you cannot locate is not a finding.
• Log the defect. Do not fix it in the moment. Findings get dispositioned later, alone, with time to think. This rule is worth more than the other eleven.
• AI is allowed and must be logged. Rep 7 uses an assistant deliberately. Every assistant finding enters the log with source: ai pass and verified: no until you open the document and check it. Record model, prompt, and outcome in docs/ai-usage.md.
• You need one human being. Rep 6 cannot be done with an assistant, a rubber duck, or a second reading. Book that person on Monday. This is the single most common reason students lose points this week.
• Time box: roughly 15 hours. If any rep is eating the budget, log the real number and move on. The audit in Rep 12 wants the truth, not a tidy story.

Templates you will use: code/design-review-checklist.md, code/review-defect-log.csv, code/baseline-and-change-control.md, and code/pace-audit.py. Worked examples of every artifact are in Appendix B.

Block A — Prepare the package

Rep 1 — Assemble the package and gate it yourself

Put the six review artifacts in one place, at one version, and tag the version you are asking people to read.

# Confirm every artifact exists and is current. Six artifacts, seven paths:
# the Week-4 non-functional requirements live inside docs/requirements.md.
ls docs/requirements.md docs/definition-of-done.md docs/adr/ \
   docs/architecture.md docs/plan.md docs/risk-register.md docs/hours-log.csv

# Pin the version being reviewed. A review of a moving document is not a review.
git add docs/ && git commit -m "docs: freeze review candidate for design review"
git tag -a spec-review-candidate -m "Package for the Week 8 design review"
git push origin spec-review-candidate

Then act as the moderator and apply the entry criteria at the bottom of code/design-review-checklist.md. If a load-bearing section says TBD, if a diagram is a whiteboard photograph, or if the package cannot be read in forty-five minutes, you do not have a package yet — fix that before Rep 2.

Write: three sentences naming what you had to fix to pass your own entry criteria. If the answer is “nothing,” you did not look hard enough.

Rep 2 — The traceability spot-check

Pick ten requirement ids — every Must you have, plus enough Shoulds to reach ten. For each, trace it forward through your own documents and record what you actually find.

An orphan is a requirement with no design, no task, or no test. Every orphan is at minimum a Major defect: it is a promise with nothing behind it. Also run it backwards — find one component in your technical specification that traces to no requirement. That is gold plating, and it is hours you were about to spend for free.

Write: the completed table, plus one paragraph on what the orphans have in common. They usually do.

Rep 3 — Write the reviewer’s brief

One page, at the front of the package. Section 8.3 of Chapter 8 shows the bad version and the good one. Yours must contain all five moves:

1. Bound the reading — which documents, which sections, how many pages.
2. Name the checklist and which areas of it you want used.
3. Name the question you most want answered.
4. Rule things out — what you are not asking about, so they stop being polite about it.
5. Pin the version — the tag and commit from Rep 1, plus the time box.

Write: the brief itself, committed as docs/review/reviewer-brief.md. Then read it back and ask: could a competent stranger start reading in under two minutes? If not, cut it in half.

Block B — Run the review

Rep 4 — The solo walkthrough, cold and out loud

At least 48 hours after you last edited the specification — not the same day, the delay is the mechanism — read docs/architecture.md aloud, section by section, in the Reader’s role. Do not read what you meant. Read what is on the page.

Three amplifiers, use at least two: read it on a different device or in print; use a text-to-speech reader and listen; read it as a named persona (the engineer who inherits this in January and has never met you).

Every time you hesitate, backtrack, or add a spoken clarification that is not written down — that is a defect. The clarification you just said out loud is information the document does not contain.

Produce: at least six findings in the log format, each with a location. Write: the one sentence you had to explain out loud that surprised you most.

Rep 5 — Run the Design Review Auditor

Open The Design Review Auditor on the chapter page. Work all six areas — requirements traceable, interfaces specified, data model sound, risks owned, definition of done written, plan within budget — answering yes / no / partial with a real evidence note on every item.

The discipline that makes this rep worth anything: no evidence, no yes. If you cannot name the section, the requirement id, or the table row, the honest answer is partial.

Export the seeded defect log and merge it into docs/review/defect-log.csv.

Write: your readiness score, the widget’s top three send-backs, and — this is the part that teaches — which item you wanted to answer yes and had to answer partial.

Rep 6 — Forty-five minutes with one human being

Send the package and the brief from Rep 3 to one actual person: an advisor, a classmate, a working engineer, or the stakeholder from Week 2. Give them the checklist and a 45-minute box. Then sit with them.

Your job in that meeting is recorder, and it is harder than it sounds:

• Write every finding down with its location, in their words, before you respond.
• Do not explain what you meant. If they misread it, the document is unclear and that is the finding.
• Do not design the fix in the room. “Logged. Moving on.”
• When they go quiet, ask the two questions that pull the most out of people: “What would you need to know that isn’t here?” and “Which part would you be most nervous to build?”

Produce: their findings in the log, tagged with their name in the found_by column. Write: the finding that stung, and the honest reason it stung.

Coach’s Note — If your reviewer gives you zero findings, the review failed. Push once: “Which section is the weakest?” Everyone will answer that question.

Rep 7 — The adversarial AI pass, then the verification

Give an assistant your requirements specification, your technical specification, and the checklist areas, using the hostile-reviewer prompt shape in section 8.9. Ask for defects, not improvements, and demand a location and a severity on every one.

Then do the half nobody does. Open the document and check every single finding. For each, record one of: confirmed (it is a real defect), rejected — not a defect (with the reason), or fabricated (the section or requirement id does not exist).

Produce: every AI finding in docs/review/defect-log.csv with source: ai pass, including the rejected ones, with reasons. Add the prompt and outcome to docs/ai-usage.md.

Write: your fabrication rate — fabricated findings over total findings — and one sentence on what that number means for how you use this tool in Week 12. Then answer the question that matters most: name one defect your human reviewer found that the assistant did not, and say why the assistant could not have found it.

Block C — Disposition and rework

Rep 8 — Severity, disposition, owner, due week

Merge every finding from Reps 4–7 into one log at docs/review/defect-log.csv, deduplicated. Then give each row all six of: severity (Critical / Major / Minor / Trivial / Question), disposition (Fix now / Deferred / Rejected / Duplicate / Accepted risk), reason, owner, due week, and verified.

Two rules that are graded:

• Every rejection needs a written reason. “Rejected — not a defect” with an empty reason column is worth zero.
• Severity and disposition are independent. A Major can be deferred if you say why and raise a change request. A Minor can be fixed today.

Write: the counts — how many Criticals, Majors, Minors — and the one disposition you are least comfortable with.

Rep 9 — Rework the Majors, then verify them separately

Fix every Critical and every Major dispositioned Fix now. Commit the rework with the defect ids in the message:

git commit -m "docs: rework DR-001, DR-003, DR-007 from design review"

Then, on a different day, do the verification pass: reopen the original finding text — not your memory of it — and confirm the change actually resolves it and did not create a new problem. Set verified to yes and record the date. Fixed is not verified. A Major that is fixed but unverified is still open.

Write: one finding whose fix created a second finding. There is usually one, and catching it is the whole point of verifying separately.

Block D — Baseline, change control, and the audit

Rep 10 — Declare the baseline

Use the declaration template in code/baseline-and-change-control.md.

git add docs/ && git commit -m "docs: design review report and rework complete"
git tag -a spec-baseline-v1.0 -m "Specification baseline: design review <date>, accept with rework"
git push origin spec-baseline-v1.0

Write docs/baseline.md naming every frozen artifact with its repo path and version, the commit SHA, the tag, the review report, and — do not skip this — the open items carried past the baseline, so a deferred defect does not become a forgotten one.

Write: three sentences on what is now frozen and what is deliberately not, addressed to the engineer who will read this in Week 16.

Rep 11 — Stand up change control and work one real request

Create docs/change-requests/ and copy the change-request template in. Add the change-log table to the top of CHANGELOG.md. Then write CR-001 for a change you already know is coming — the most honest candidate is the deferred defect from Rep 8, or the scope cut Rep 12 is about to demand.

Fill in every field, including the ones that hurt: requirements affected by id, hours added or removed, schedule effect, risk effect, the decision, and the rationale. Write the rationale even though you are approving your own request. Especially then.

Write: the threshold rule in your own words — the five kinds of change that will require a CR for the rest of this course, and one kind that deliberately will not.

Rep 12 — The halfway audit and the honest paragraph

Run the audit against your real log:

python3 pace-audit.py docs/hours-log.csv --through 8
python3 pace-audit.py --demo          # see a worked example first if you like

Then answer the six questions from section 8.8 in writing, each with evidence:

1. Hours — logged versus budgeted, and the trend across the eight weeks.
2. Scope versus budget — what does your Week-7 plan estimate for the Must set? Measure it against the right number, not the ninety in the course budget table: of the 135 hours left after Week 7, 48 go to chapters, quizzes, reps, and the presentation, leaving 87 for the project, and after the declared 25% buffer about 65 plannable hours — of which testing, documentation, and deployment claim roughly 25. Above 65 hours for the whole plan, or roughly 40 for the Must set alone, you cut this week.
3. Risk — has any trigger already fired? Check each one; do not recall it.
4. Environment — push a trivial commit and confirm the whole loop still runs. When does your free tier end?
5. Novelty load — how many planned tasks are things you have never done?
6. The user — is your stakeholder still available and still interested?

Produce: docs/review/week-08-audit.md. Write: the paragraph. Not the numbers — the paragraph that says what you are changing because of them. “I am 51 hours behind, my Must set estimates at 104 hours against 90 remaining, so CR-001 moves offline mode out of v1 and CR-002 demotes the recipe ranker to a Should” is an audit. “I need to work harder” is a wish.

Done? One Last Thing.

Write the design review report — one to two pages at docs/review/<date>-design-review-report.md — and sign it. This is the artifact a real moderator produces, and it is the thing a grader reads in Week 16 to see whether this week happened.

It contains, in this order:

1. Header — date, materials reviewed with their tag and commit, participants and roles, time spent.
2. Findings summary — counts by severity and by source (walkthrough, auditor, human, AI pass).
3. Disposition summary — how many fixed, deferred, rejected, accepted as risk.
4. Open items carried past the baseline, each with a due week.
5. The decision — Accept, Accept with rework, or Re-review required — with one paragraph defending it. Most students land on Accept with rework, and that is a good outcome, not a bad one.
6. The pace correction from Rep 12, in one sentence.
7. Your name and the date. You are the moderator of record. Sign it.

Then commit, push, and confirm spec-baseline-v1.0 is visible in your remote repository. On Monday, construction starts against exactly what that tag says.

Normal-tier rubric (out of 100)

Going further (optional, +up to 25% extra credit)

• A second reviewer from outside computer science. Give your requirements specification to someone who will actually use the system and is not an engineer. Log what they could not follow. Non-engineers find requirement defects that engineers read straight past, because engineers auto-repair ambiguity.
• Re-review the sections you reworked, cold, forty-eight hours later, and log what the rework broke. Second-order defects are real and nobody looks for them.
• The judgment memo an assistant cannot write for you (this is the one that earns the top of the range): two pages arguing the weakest part of your own baseline, why you are proceeding anyway, the specific result that would tell you the decision was wrong, and the week you will check. Name the requirement you are most afraid of and say what you will cut if Week 11 proves you right. Nothing in that memo can be generated, because all of it requires owning a claim about your own capacity — and ownership is the one thing a tool cannot do for you.

Up next: the midterm checkpoint quiz on the course site — auto-graded, cumulative over Weeks 1–8; study from the table in section 8.15 of Chapter 8. Then Chapter 9, where the arguing stops and one real request travels the whole system end to end. Reference: Appendix B (worked examples of every artifact), Appendix C (the grading contract), Appendix E (glossary).