Chapter 8 — The Design Review

“Given enough eyeballs, all bugs are shallow.” — Eric S. Raymond, The Cathedral and the Bazaar (1999), naming what he called Linus’s Law

“Without counsel plans fail, but with many advisers they succeed.” — Proverbs 15:22 (ESV)

Why This Matters

You are at the hinge of the course. Behind you are seven weeks of deciding: a charter, a scoped idea, a requirements specification, the non-functional requirements nobody writes down, a technology evaluation defended in architecture decision records, a technical specification, and a plan with estimates, a schedule, and a risk register. Ahead of you are eight weeks of building: a walking skeleton, two iterations, a test suite, documentation, a deployment, a presentation, and a handoff.

This week is the gate between them. In industry it has a name — the design review, sometimes the critical design review or the phase gate — and it is one of the few rituals that survives in every kind of software organization, from a three-person startup doing a Friday design walkthrough to a defense contractor running a formal Fagan inspection with a moderator and a recorder and a signed report. The reason it survives is unglamorous and provable: reviews find a class of defect that testing cannot find at all. A test can only fail against a specification. If the specification is the thing that is wrong, every test passes and the project still dies.

The hat you wear this week is the one that feels worst on a solo capstone: the reviewer’s, worn over your own work, and then the configuration manager’s, the least glamorous title in software and the one that decides whether anybody can reconstruct in Week 16 what you decided in Week 6. To wear the reviewer’s hat you must first take off the author’s, and that is genuinely hard, because you cannot see your own blind spot — that is the definition of a blind spot. This chapter is a set of techniques for manufacturing distance from your own document, plus one piece of advice that beats all of them: get one actual human being to read it. Forty-five minutes of somebody else’s attention is worth more than anything else you will do this week. Then you will do something that feels like the opposite of agile and is not: you will freeze the specification into a baseline, and everything that changes after this week will change through a written change request — not because paperwork is virtuous, but because in Week 14, when you are debugging at eleven at night and the spec says something you do not remember agreeing to, the change log is the only thing standing between you and rewriting your own history. The baseline is how a project remembers itself.

The AI thread runs through the week from both sides, and this is one of the weeks where it matters most. As a tool, an assistant is a genuinely strong first-pass reviewer: it will read your requirements specification against your technical specification and find the seven requirements you never designed for, faster than a human could, and without getting bored. As an accountability problem, it is the reviewer that has never shipped anything, never been paged at 3 a.m., and has no stake in whether you finish — so it will hand you confident, well-formatted findings, some of which are wrong, and a few of which cite section numbers that do not exist. Every finding it produces enters your defect log marked unverified. The spine rule holds all week: the assistant accelerates the search, you decide what is a defect, and you sign the review report.

And so the apologetic question, which is the oldest question in the practice of engineering and older still than engineering: why do we need other eyes? Not “why is peer review a nice idea,” but why is it that a human being — competent, careful, honest, working hard — cannot reliably see what is wrong with their own work? That is a claim about what a person is. It is worth taking seriously, because everything about how you run this week depends on the answer.

8.1 — Why Reviews Find Defects That Testing Never Will

Start with the thing students get wrong. Testing and reviewing are not two ways of doing the same job. They find different defects, and the ones review finds are the expensive ones.

A test is a comparison between behavior and an expectation. If your expectation comes from the specification, and the specification is wrong, the test agrees with the bug. Every green check mark in your pipeline is a statement about consistency, not correctness. Consider the classes of defect the two techniques can reach:

Look at the bottom four rows. Those are the defects that end capstones, and none of them are reachable by any test you could write, because a test cannot notice an absence. This is the deep reason reviews exist: a test can only ask whether the code matches the plan; a review can ask whether the plan is any good.

There is a second reason, and it is economic. A defect found in a requirements document costs a rewritten sentence; the same defect found in Week 13 costs a rewritten module, the tests around it, the documentation about it, and hours you no longer have. You do not need a precise multiplier to act on this — the direction has been reported consistently across the software-engineering literature since Barry Boehm’s cost-of-change work in the early 1980s, and every engineer you will ever work with has felt it personally. A sentence is cheap. A module is not.

The practice has a lineage worth knowing by name, because you will hear these words in your first job. Michael Fagan at IBM published the formal software inspection in 1976 — roles, entry criteria, a rate limit, a defect log, a rework step, a re-inspection gate. IEEE Std 1028, the standard on software reviews and audits, still distinguishes the family: a management review checks progress, a technical review evaluates fitness for purpose, an inspection is the formal defect-hunting version with defined roles, a walkthrough is the author-led lighter version, and an audit is an outside conformance check. What you run this week is an inspection wearing a walkthrough’s clothes: formal enough to produce a real defect log, light enough for one student in an afternoon.

Coach’s Note — Every senior engineer has a story about the review that saved a quarter. Nobody has a story about the review that wasted an hour, because you cannot tell the story of the bug you never shipped. The value of this week is invisible by construction. Do it anyway.

8.2 — The Roles: Author, Moderator, Reviewer, Recorder — and How to Fake a Team of One

A real inspection distributes four jobs across four people, and the distribution is the mechanism, not the ceremony.

You have one person. Here is how to fake the rest, in order of how much they actually buy you.

1. Recruit one human. This is not optional in spirit. An advisor, a classmate, a working engineer you know, the roommate who is your actual stakeholder. Give them the package, the checklist from code/design-review-checklist.md, a 45-minute time box, and a specific charge. One outside reader finds what no technique in this list will find, because they do not know what you meant.

2. Separate the roles in time, since you cannot separate them in people. Be the author on Monday, the reader on Wednesday — never the same day. Forty-eight hours of cold is the cheapest distance you can buy. Your memory of what you meant fades slower than your memory of what you wrote, and the gap between them is where the defects live.

3. Be the Reader out loud, literally. Read the specification aloud, or paste it into a text-to-speech reader and listen. Ambiguity is audible in a way it is not visible. When you hear yourself say “the system should handle invalid input appropriately” in your own voice, you will wince. That wince is a defect.

4. Change the medium. Print it. Export a PDF and read it on a phone. Read it in a different font. This is defamiliarization, and it works for the same reason proofreaders read backwards: your eye skips what it has already parsed.

5. Let the checklist be your proxy reviewers. A checklist is other people’s memory of what goes wrong, compressed. Every item in code/design-review-checklist.md is there because somebody’s project died for want of it.

6. Play a named reader, not a generic one. Not “would this be clear?” — clear to whom? Read it as the engineer who inherits this in January and has never met you; as the grader with forty minutes for your repository; as the tired version of you in Week 13. Each persona finds different holes. And 7. use an assistant as a third reviewer, never the only one — section 8.9.

Coach’s Note — If you can only do one of these seven, do the first. A capstone student who never once put their specification in front of another human being has not been reviewed; they have been reassured.

8.3 — Preparing the Review Package

A reviewer’s time is the scarcest resource in the week. The package is how you refuse to waste it.

The package is six artifacts and one page of instructions:

1. The requirements specification, with the Must set marked (Week 3).
2. The non-functional requirements, constraints, and the definition of done (Week 4).
3. The architecture decision records (Week 5).
4. The technical specification with its diagrams (Week 6).
5. The work breakdown, schedule, and risk register (Week 7).
6. The hours log, current through this week (Week 1 onward).

Plus the reviewer’s brief — one page, at the front. This is the part students skip, and it is the part that determines whether the review is useful.

Here is a bad brief and a good one.

Bad:

Hey — attached is my capstone design doc. Let me know what you think!
Any feedback welcome.

That brief guarantees you get comments on your font. “Any feedback welcome” outsources the decision of what matters to someone who knows less about your project than you do, and people who do not know what is wanted default to the safest possible criticism, which is cosmetic.

Good:

Design review: PantryPilot, senior capstone, baseline gate.

What I need (45 minutes, please do not go over):
  1. Read docs/requirements.md section 5 (the Must set, 14 requirements)
     and docs/architecture.md sections 5-7 (interfaces, data model, flows).
  2. Use docs/review/design-review-checklist.md, areas 1-3.
  3. I am specifically asking: is there a Must requirement this design does
     not satisfy, and is there anything in the interface section a developer
     could not build from?

NOT asking for: wording, formatting, or whether the idea is good. Settled.
Format: one line per finding, with the section number. Do not soften it.
I will not argue in the meeting; I will log it.

Materials: tag spec-review-candidate, commit 4f2a91c.
Time box: 45 minutes reading, 45 minutes together Thursday.

That brief bounds the scope to something a person can finish, names the checklist, names the question it most wants answered, rules things out so the reviewer need not be polite about them, and pins the version — a review of a document that changed mid-review is not a review.

Entry criteria. In a formal inspection the moderator refuses to hold the meeting if the package is not ready; be that moderator to yourself. Do not spend a reviewer’s forty-five minutes if any load-bearing section says TBD, if you have not run the checklist over it yourself, if the diagrams are whiteboard photographs, or if the package is too long to finish. And respect the rate limit: the widely cited SmartBear analysis of peer code review at Cisco reported that defect-finding effectiveness fell off sharply past about an hour in a sitting and past a few hundred lines of material. Treat the numbers as indicative and the shape as certain — attention is a consumable. Two focused forty-five-minute sessions beat one three-hour slog.

8.4 — The Walkthrough: Log the Defect, Do Not Fix It in the Room

Here is the single rule that separates a review that works from a meeting that feels productive and produces nothing.

You are hunting defects. You are not solving them.

The moment somebody says “well, what if you used a queue for that,” the review is over. Everyone’s attention has left the document and gone to the design of the fix, the highest-status and most fun activity in engineering, and it will not come back. You will spend thirty minutes on a solution to the first problem you found and never reach section 7, where the real one was.

Watch it happen.

The bad walkthrough:

Reviewer: In section 6.2, quantity is an integer, but requirement FR-007 talks about half a bag of flour. Author: Oh — yeah. I could make it a float? Reviewer: Floats round badly. Store the smallest unit as an integer? Author: But units vary. Grams for flour, count for eggs… does the barcode API return units? Reviewer: Probably? Let me look…

— twenty-two minutes later they have designed a unit-conversion subsystem, logged zero defects, and never opened section 7, where the failure flow that loses data on a failed write is described.

The good walkthrough:

Reviewer: In section 6.2, quantity is an integer, but FR-007 talks about half a bag of flour. Author (recording): Got it. DR-001, docs/architecture.md 6.2, quantity type cannot satisfy FR-007. Major. Moving on — section 6.3. Reviewer: You could store it in grams — Author: Logged. I will decide that this weekend. Section 6.3, expiry dates.

That is the whole discipline, and it is rude in exactly the right way. The moderator’s line is three words: “Logged. Moving on.” Write it on a sticky note. When you run the review alone, you are the moderator, and the person you must interrupt is yourself. Two rules follow from the same principle. Findings are about the document, not the author — “section 6.2 does not specify units” is a finding; “you forgot units” is a finding with a small insult stapled to it, and the insult is what the author will remember. And every finding gets a location: a finding without a section number is a mood, and the recorder’s job is to refuse it.

Coach’s Note — The reason “log it, do not fix it” is hard is that fixing feels like progress and logging feels like admitting failure. It is exactly backwards. In the room, your throughput is measured in defects found per hour. Solving is what the rest of the week is for.

8.5 — Severity, Disposition, and the Follow-Up

The review produces a list. The list is worth nothing until every item on it has been dispositioned — decided, in writing, by the author.

Separate two things students constantly merge. Severity is how bad it is if it ships. Disposition is what you are going to do about it. A Minor defect can be fixed today; a Critical defect can be deferred if you write down why. They are independent axes.

Severity:

Disposition — one of five, every one requiring a written reason. Fix now (corrected before the baseline; say what changed). Deferred (real, but not before construction; raise a change request, give it a week). Rejected — not a defect (the reviewer was mistaken; write why — this is the one people skip and the one that protects you, because next month you will not remember why you ignored it). Duplicate of finding X. Accepted risk — you know, you are proceeding anyway, and it goes in the risk register with an owner.

Here is the good-versus-bad that matters most this week, because most students’ first defect log looks like the left column.

Bad:

3 | data model | wrong types | high | will fix

Six words, all useless in a month. Which document? Which section? Which requirement does it break? Wrong how? Fixed how? Verified by what?

Good — one row from code/review-defect-log.csv:

DR-001 | self | walkthrough | data-model | docs/architecture.md 6.2 PantryItem | FR-007 |
"quantity is typed integer but FR-007 requires 'half a bag' amounts and NFR-02 requires
unit conversion; the type cannot satisfy the requirement" | Major | Fix now |
"Type change to decimal plus a unit field; spec section rewritten" | me | 8 | yes

That row is a complete unit of accountability: who found it, how, where it is, which requirement it threatens, how bad, what you decided, what you actually did, who owns it, when it is due, and whether the fix was verified. Fourteen of those rows are a review report. Copy the template with its worked PantryPilot rows to docs/review/defect-log.csv and use it for the rest of the course — in Week 11 it grows up into the defect log for the running system, with the same columns.

Verification is a separate step from fixing. “Fixed” means you changed something. “Verified” means somebody checked that the change actually resolves the finding and did not create a new one. On a team, the moderator verifies. Alone, verify on a different day, against the original finding text, and record the date. A Major that is fixed but unverified is not closed.

The follow-up decision. At the end of the review, the moderator records one of three outcomes — this is the actual gate:

8.6 — The Baseline: What Freezing the Specification Actually Means

A baseline is a set of documents that has been formally reviewed and agreed, that from that moment forward serves as the basis for the work, and that may be changed only through a defined change procedure. That is the practitioner’s definition and it has three parts, all load-bearing: reviewed, agreed, changed only through a procedure.

Two things a baseline is not. It is not a claim that the specification is correct — it is a claim that it is settled, that you and your reviewers looked, decided, and are now going to build against this rather than keep arguing. Certainty is not available; agreement is. And it is not the opposite of agile, which is worth ten seconds because students hear “freeze the spec” and think waterfall. Agile teams baseline constantly — they just do it at smaller granularity and call it a sprint commitment, a definition of ready, a merged and tagged API contract. The principle is identical: at some point the arguing stops and the building starts, and the transition is recorded. What waterfall got wrong was the size of the frozen block and the difficulty of changing it, not the existence of a frozen block. You are freezing a specification you can amend in twenty minutes with a written reason. That is not a straitjacket. That is a memory.

What you actually do, in about twenty minutes:

# 1. Make sure the rework is committed and the review report is in the repo.
git add docs/ && git commit -m "docs: rework from design review DR-001..DR-013"

# 2. Tag it. The tag is the baseline; the tag is what you cite forever after.
git tag -a spec-baseline-v1.0 -m "Specification baseline: design review 2026-03-05, accept with rework"
git push origin spec-baseline-v1.0

# 3. Write the declaration.
#    docs/baseline.md - what is frozen, at which commit, with which open items.

The declaration template is in code/baseline-and-change-control.md. It names every frozen artifact with its repo path and version, the commit SHA, the git tag, the review report, and — the part people forget — the open items carried past the baseline, so that a deferred defect does not quietly become a forgotten one. Compare the two ways students do this.

Bad baseline: “I finished the spec.” No tag, no declaration, no report. The document keeps changing silently over the next eight weeks. In Week 14 the specification describes a system that was never built, and nobody — including its author — can say when it diverged, or which version the grader is reading.

Good baseline: A tag. A commit SHA. A one-page declaration listing eight frozen artifacts and two carried-open defects. Every subsequent change to those eight artifacts arrives with a change-request id in the commit message. In Week 14 you run git diff spec-baseline-v1.0 -- docs/ and see, in one screen, everything your project learned in eight weeks — and that diff is half of your retrospective already written.

Coach’s Note — The baseline is the moment your project stops being an idea you are having and becomes an artifact that exists independently of your memory. Every professional habit in this course points at the same thing: build a project that survives your forgetting. You will forget. Everyone does.

8.7 — Change Control From Here to Week 16

The specification will change. Of course it will — you are about to learn things by building. Change control is not a way to prevent change; it is a way to make sure change is decided rather than drifted into.

There are two failure modes and they look nothing alike. Scope creep by accretion: no single addition is unreasonable — in Week 10 you add a small filter, in Week 11 the barcode scanner should really handle QR codes too, in Week 12 a settings page because it is only an hour — and by Week 14 the Must set has grown forty percent, none of it written down, and you are behind for reasons you cannot reconstruct.

Silent scope reduction is the more dangerous one, because it is invisible and it feels like nothing happened. In Week 12 offline mode turns out to be hard, so you quietly stop working on it. Nobody decides anything. In Week 16 the grader opens docs/requirements.md, finds FR-016 marked Must, finds no implementation, no test, and no explanation — and marks it incomplete. Which it is. Had you raised a change request in Week 12 with an impact assessment and a decision, that same missing feature would have read as project management, and the fourteen hours you saved would have been visible as a deliberate trade. That is the entire argument, and it is worth saying plainly: a documented scope reduction is a professional act; an undocumented one is an incomplete project.

The threshold rule — from code/baseline-and-change-control.md. Raise a change request when the change does any of these:

1. Adds, removes, or materially rewords a Must requirement.
2. Changes an interface contract or the data model.
3. Moves a milestone date, or changes the total plan by more than four hours.
4. Changes the stack.
5. Changes the definition of done.

Everything else is an ordinary commit with a clear message. Do not bureaucratize your own project — a solo capstone with a fourteen-step change process will simply be ignored by its only participant, which is worse than no process.

Bad change: a message to a friend, and nothing else — “dropping the barcode scanner, it’s too hard.” Nothing in the repository. No impact assessment. No decision. No date. Fourteen hours of plan disappear and reappear as unexplained slack, and in Week 16 the requirement is still marked Must.

Good change: docs/change-requests/CR-003-drop-offline-mode.md, twenty-five lines: what changes (FR-016 moves from Must to Out of Scope for v1), why (the sync-conflict design is a two-week problem, not a one-week problem, discovered in the Week-9 spike), the impact (FR-016 and NFR-07 affected; minus fourteen hours; risk R-04 closes; WP-6 removed from the schedule), the decision (approved after a ten-minute conversation with the instructor, since a Must requirement is moving), and the applied checklist (spec updated, matrix updated, plan re-baselined, CHANGELOG.md row added). Twenty-five lines that convert a retreat into a decision.

Who decides? In industry, a change control board. As a team of one you are the board — with one exception you should honor: moving a Must requirement out of scope is a conversation with your instructor, not a private edit. It affects your grade, and a two-minute conversation in Week 12 is much cheaper than a surprise in Week 16.

8.8 — The Halfway Audit: Are You On Pace, Honestly?

Half the budget is gone. One hundred and twenty of your two hundred forty hours, and the application does not exist. Read that again, then let go of the panic — it is on purpose, and it is worth understanding why. Here is the course’s budget, stated plainly:

The first half bought you something specific: it converted the hours that remain from discovery into construction. The most expensive hour in software is the one spent building something before you knew what it was. Read the ninety in the construction row carefully, though — it is a course budget, not a project budget. Chapters, quizzes, and reps are still inside it, and question 2 below does that subtraction for you. What survives the subtraction will be efficient time, because the arguing is done — which is exactly why this week’s baseline matters, and exactly why the audit below is not optional.

The seven questions. Answer each with evidence, not a feeling.

1. Hours. What does your log actually say? Run code/pace-audit.py against docs/hours-log.csv and read the variance line. Not the number you remember — the number you logged.
2. Scope versus remaining budget. What does your Week-7 plan estimate for the Must set? Measure it against the right number, which is not the ninety in the table above. Chapter 7 already did this arithmetic: of the 135 hours left after Week 7, 48 go to chapters, quizzes, reps, and the presentation, leaving 87 hours for the project itself across Weeks 8–16 — and after the declared 25% buffer, about 65 plannable hours. Those 65 are not all features, either: testing, documentation, and deployment claim roughly 25 of them in Chapter 7’s worked plan, which leaves about 40 for the build. The rule I will commit to: if your whole plan estimates above 65 hours, or the Must set alone above roughly 40, cut this week. Every plan you have ever made has been optimistic in the same direction.
3. Risk. Has any risk’s trigger already fired? Go read the register and check them one at a time. A risk you wrote down in Week 7 and never looked at again is a wish.
4. Environment. Does your workbench still work? Does the free tier still exist and when does it end? (Appendix A has the watch list.) Push a trivial commit and confirm the whole loop still runs.
5. Novelty load. How many tasks in your plan are things you have never done? Count them. Each one is an estimate you cannot trust and a spike you should schedule.
6. The user. Is your stakeholder still available and still interested? If your only user has stopped answering, that is a Critical defect in the project, not in the document.
7. The cut order. Open docs/scoping-decision.md and read the cut order you pre-committed in Week 2 — the first three features that die, in order, and the evidence that would tell you it is time. Two questions, in writing: has that trigger fired? and is the order still right? If the trigger fired, cut now and raise the change request today; that is what you wrote it for. If the order is wrong because you have learned something real since Week 2, say what you learned and rewrite it — that is a legitimate revision, and it is why you date these things. What does not count is quietly deciding the trigger did not really mean it. You wrote that sentence in the one week of this course when you had nothing invested and no reason to lie to yourself. Believe them.

Cut here or cut later. This is the honest part of the chapter. The cheapest scope cut in the entire course is the one you make this week, because nothing has been built. A requirement removed today costs the twenty minutes to write CR-001; the same requirement removed in Week 13 costs the hours you already spent on it, plus the hours to rip it out, plus the documentation that now lies. And the failure mode to name and refuse: passing the audit by adjusting the budget instead of the scope. “I’ll do twenty-five hours a week in October” is not a plan; it is a hope with a number attached, and you have eight weeks of your own logged data proving what you actually do. Estimate with the velocity you have, not the one you would like to have.

Coach’s Note — Nobody has ever regretted cutting scope in Week 8. Hundreds of students have regretted not cutting it. The project that ships four features completely beats the project that ships seven features at eighty percent — every time, on every rubric, in every job interview.

8.9 — The Adversarial Review: Using an Assistant, and Where It Fails

An assistant is the best first reviewer you have available and the worst only reviewer you could choose. Both halves are true and the week works only if you hold them together.

What it does genuinely well. It reads two documents at once without getting bored, which makes it strong at exactly the defect class that is tedious for humans: cross-document traceability (“list every requirement id in the first document that is not designed for in the second, and every component in the second that traces to no requirement”), coverage of the unhappy path (“for each endpoint in section 5, list the error conditions the specification does not describe”), and measurability checks (“which non-functional requirements lack a metric, threshold, condition, or measurement method?”). The single best prompt is the absence question: “What does this specification not say that a developer building it in ninety hours would have to ask me?”

A prompt shape that beats “review my design”:

You are a skeptical senior engineer reviewing a design for a project that ONE student
must finish in 90 hours. You are hunting defects, not suggesting improvements.

For every finding output exactly: section | requirement id (or "none") | what is wrong |
severity (Critical/Major/Minor) | why it matters during construction.

Do not propose solutions. Do not comment on style. If you are not certain a section
says what you claim, mark the finding "UNVERIFIED".

[paste requirements spec] [paste technical spec] [paste the checklist areas]

Where it fails, and these are not small.

• It invents specifics with total confidence. It will cite section 4.7 of a document that ends at 4.5, and FR-021 in a specification that ends at FR-018. Rows DR-008 and DR-009 in code/review-defect-log.csv are both assistant findings, both wrong, and both in the log anyway, marked Rejected with a reason. Keep them — the rejection rate is data. Two rejections out of four assistant findings tells you how hard to squint at the next batch.
• It cannot see your velocity or your novelty load. It does not know you have logged 8.6 hours a week rather than 15, or which of these technologies you have never touched. It will bless a plan that cannot be built by you.
• It has no stake. It has read everything about software and shipped nothing, and the difference shows up precisely at the judgment calls: whether this requirement is worth building, whether this user wants it, whether you should cut.
• It agrees. Ask “is this a good design?” and you get a graded, encouraging answer, because helpfulness is what it optimizes. The adversarial framing helps; it does not cure.

The rule for the week, and it is not negotiable: every assistant finding enters the defect log with source: ai pass and verified: no, and you resolve it by opening the actual document and looking. A finding you did not check is a rumor.

The other direction — reviewing AI-drafted design documents. If any part of your specification was drafted with an assistant, review that part twice, because generated prose is fluent, and fluency reads as correctness to the human eye. The specific tells to hunt for: numbers that sound authoritative but trace to nothing (“the system shall respond within 200ms” — says who?); requirements that restate their own heading; error handling that says “handle errors gracefully”; interfaces that name an endpoint and a verb but no payload; and paragraphs that are perfectly organized and say nothing you could build from. And here is the courtesy rule: never spend a human reviewer’s forty-five minutes on a document you have not self-reviewed. Their attention is the scarcest thing in your project. Do not burn it finding what a checklist would have caught.

Coach’s Note — Log your review prompts and the assistant’s findings in docs/ai-usage.md as you go — which model, what you asked, what you accepted, what you rejected and why. In Week 16 that file is graded, and reconstructing it from memory in Week 15 is miserable and slightly dishonest.

8.10 — Interactive Lab: The Design Review Auditor

Below this chapter on the website is The Design Review Auditor. Use it after you have assembled your package and before you sit down with your human reviewer.

You will walk your own baseline through a reviewer’s checklist grouped by the same six areas as code/design-review-checklist.md: requirements complete and traceable, interfaces fully specified, data model sound, risks owned, definition of done written, plan within budget. Each item is answered yes, no, or partial, and each answer wants a short evidence note — a section number, a requirement id, a table row. An item with a “yes” and no evidence is the thing the widget is built to catch, so do not do it; it is a lie you tell yourself in eleven seconds.

The Auditor gives you three things back. A readiness score, which is a temperature, not a grade. A prioritized list of what a real reviewer would send back before approving — ordered so the top item is the one that would block your baseline. And a printable defect log seeded with every “no”, which you export and merge into docs/review/defect-log.csv so those findings enter the same accountable pipeline as the human ones. What it teaches is worth naming: the difference between having a document and having evidence. Most students discover, item by item, that four or five things they were sure they had specified exist only in their head. Better to find that here, in an afternoon, than in Week 12 at the keyboard.

8.11 — Why Do We Need Other Eyes?

“Without counsel plans fail, but with many advisers they succeed.” (Proverbs 15:22, ESV)

The proverb is not a compliment to committees. It is a claim about the individual — that a plan made by one mind, however capable, has a characteristic and predictable weakness, and that the weakness is not fixed by that mind trying harder.

Every engineer eventually meets this experimentally. You proofread a document five times, ship it, and the first person who reads it finds the error in the first paragraph. You debug for three hours, describe the problem out loud to a colleague, and see it mid-sentence before they say a word. Author blindness is not carelessness. It is structural: when you read your own document, the meaning arrives from memory before your eye reaches the words, so you verify the sentence against your intent, which is the one comparison that cannot fail. You are the worst possible reviewer of your own specification, and you are worst precisely where you understand it best.

Scripture’s account of why is more interesting than “people make mistakes,” and it has two halves that must be held together. The first half is dignity. You were made in the image of a God who makes things, and the making is good. The account of Bezalel in Exodus 31 is remarkable on this point — a craftsman filled with the Spirit of God “with ability and intelligence, with knowledge and all craftsmanship” (Exodus 31:3, ESV), for the purpose of skilled work. Your specification is real work of a real kind. Review does not exist because your work is worthless. If it were worthless there would be nothing to review.

The second half is honest about limits. “The heart is deceitful above all things, and desperately sick; who can understand it?” (Jeremiah 17:9, ESV). The psalmist asks the question this whole chapter is about: “Who can discern his errors? Declare me innocent from hidden faults” (Psalm 19:12, ESV). Hidden faults — hidden not from everyone, but from him. That is exactly the design review’s problem statement, written three thousand years before Fagan wrote his. The fool’s error in Proverbs is not stupidity; it is self-sufficiency: “The way of a fool is right in his own eyes, but a wise man listens to advice” (Proverbs 12:15, ESV).

Hold both halves or you will run this week badly. Drop the first and review becomes despair — nothing you make is any good, so why write anything. Drop the second and review becomes an insult — I already checked it, what could they possibly add. The Christian answer is stranger than either: your work is genuinely good and you cannot see it clearly, and both are simply true about being a person. Which is why we were not built to work alone. “Two are better than one, because they have a good reward for their toil. For if they fall, one will lift up his fellow. But woe to him who is alone when he falls and has not another to lift him up!” (Ecclesiastes 4:9–10, ESV). That is about labor, plainly. The reviewer who finds your data-model defect is lifting you up before you fall, and Luther’s image of vocation is exactly this: God ordinarily provides for us through ordinary people doing ordinary work — the farmer, the magistrate, the neighbor, and yes, the classmate who spends forty-five minutes reading your interface section. They are, in Luther’s phrase, masks through which God works. Your reviewer is not an obstacle between you and your grade. They are a gift with a schedule conflict.

This settles how to give a review. “Faithful are the wounds of a friend” (Proverbs 27:6, ESV) — faithful, and still wounds. Paul tells the Galatians to restore a brother “in a spirit of gentleness,” and then adds, tellingly, “Keep watch on yourself, lest you too be tempted” (Galatians 6:1, ESV). The reviewer who enjoys it has already lost the thread. Specific, located, about the document, delivered without contempt: that is not just good engineering practice, it is what love looks like when it is holding a checklist.

And it settles how to receive one, which is harder. There is a Lutheran distinction that fits this week almost too neatly. The checklist accuses. It is law: here, precisely, is where you fall short — section 6.2, no units; FR-011, unverifiable; the plan is fourteen hours over. That accusation is true and you should not soften it. But the accusation of your document is not a verdict on you. You are not your specification. Your standing does not rest on the quality of your requirements engineering, and the person who knows that is the only person who can read a hard review without flinching, agree with it, and go fix it on Saturday. The students who cannot receive criticism are almost always the ones who have quietly staked something much larger than a grade on the work being good. Put that down. It was never yours to carry, and putting it down is what makes you coachable.

Last, the thing this chapter has been circling. An assistant is not counsel in the sense Proverbs means. Counsel comes from an adviser — someone with their own life, their own scars, their own stake, someone who can be wrong and know it, who bears consequences, and who can be thanked. The model has read everything and lived nothing; it agrees because agreement is what it was shaped to produce. Use it — it is a fine tool for the tedious half of the search. But the verse says advisers, and the difference is not a technicality. Go find one human being this week.

8.12 — Common Pitfalls

Pitfall: Reviewing to be reassured instead of reviewed. Example: Sending the package to the friend who always says “looks great, man” and calling it done. Fix: Pick the reviewer most likely to find something — the one who is a little intimidating. Ask for defects explicitly, name what you will not discuss, and give them a checklist. If a review produces zero findings, the review failed; it did not pass.

Pitfall: Fixing in the room. Example: The first finding turns into a twenty-minute design session for a unit-conversion subsystem, and section 5 is never opened. Fix: “Logged. Moving on.” Say it out loud, including to yourself. The recorder writes it down; the author decides disposition later, alone, with time to think.

Pitfall: Spending a reviewer’s time on a package that was not ready. Example: Handing over a specification with three TBDs, a whiteboard photo instead of a diagram, and no self-review. Fix: Run the entry criteria in code/design-review-checklist.md over your own package first. You get very few hours of other people’s attention this semester. Do not burn one on what a checklist would have caught.

Pitfall: Findings collected but never dispositioned, and a baseline that is not actually baselined. Example: Twenty findings in a note, none decided; “the spec is done” with no tag, no commit SHA, no declaration — then eight weeks of silent edits. Fix: Every finding gets a severity, a disposition, a reason, an owner, and a due week, including the ones you reject — “rejected, not a defect, because X” is a professional answer and silence is not. Then tag it, write docs/baseline.md, and carry a change-request id in every later commit that touches a frozen artifact, so git diff spec-baseline-v1.0 -- docs/ tells the truth in Week 14.

Pitfall: Treating an assistant’s finding as a fact. Example: Rewriting section 6 because a model said it violates third normal form, when it does not — or chasing a contradiction with FR-021 in a specification that ends at FR-018. Fix: Every AI finding enters the log unverified and is closed only by opening the document and looking. Keep the rejected ones with reasons; the rejection rate tells you how much to trust the next batch.

Pitfall: Passing the halfway audit by adjusting the budget instead of the scope. Example: The plan needs 104 hours, 65 are plannable, so the plan becomes “I’ll just do 25 hours a week in October.” Fix: You have eight weeks of your own logged data. Estimate with the velocity you have. Cut a requirement, write CR-001, and take the twenty-minute cost now instead of the thirty-hour cost in Week 13.

8.13 — Where Your Hours Went This Week

Roughly fifteen hours, and the shape of them is unusual — this is the only week of the course with no construction and no new document to invent.

If your real numbers differ, log the real ones. The point of the log has never been to match the plan; it is to give Week 12 a number it can trust.

8.14 — Reps: This Week’s Graded Work

There is no Milestone 8. Week 8 has no new document to produce, because the work of this week is to test the documents you already have. The reps in the exercises are this week’s graded lab — twelve of them, carrying their own hundred-point rubric, and they walk you through the whole review from package to baseline. Preview:

• Rep 1 — assemble the package and gate it against the entry criteria before anyone sees it.
• Rep 3 — write the reviewer’s brief that makes forty-five minutes of somebody’s attention count.
• Rep 6 — sit down with one actual human being and log what they say without arguing.
• Rep 7 — run the adversarial AI pass, then verify every finding against the real document.
• Rep 10 — declare the baseline: tag, SHA, and docs/baseline.md.
• Rep 12 — run code/pace-audit.py and write the honest paragraph.

Like every milestone in this course, the lab is graded twice — it carries its own milestone points, and what it produces is exactly what the Week-16 rubric pays for again: a baselined specification, a defect log with dispositions, a review report, and a change-control process with a real change in it. Skipping it does not save you the points. It forfeits them once and defers them again to a week with no time left. (Appendix C has the full contract.)

Do the on-page Check Your Reps quiz when you finish the chapter — then take Week 8 Quiz and the Design Review Checkpoint in Canvas, the two graded items this week carries. Then go to the lab.

8.15 — The Midterm Checkpoint

Week 8 carries two graded quizzes: the ordinary Week 8 Quiz, and the Design Review Checkpoint — auto-graded, cumulative over Weeks 1–8, and worth 30 points against the weeklies’ 10, which makes it about three normal weeks. Both sit in the 15% quiz bucket. The checkpoint is longer than a normal week’s quiz because it covers eight weeks of vocabulary — the language of the software development life cycle, which you will be expected to speak in every interview you take next spring. One idea and one anchor per week; if you can say both from memory, you are ready.

Study it like a warm-up — quickly, to loosen what is already there. Your real hours this week go to the review.

8.16 — Coach’s Final Word

Eight weeks ago you had an idea. Today you have a specification that has been read by someone who is not you, a list of the things that were wrong with it, a written decision on every one, and a tag in your repository that says this is what we agreed.

That tag is the difference between a student project and a professional one. Not the code — you have not written any yet. The tag. It means there is a version of the truth that exists outside your head, and that from here on, when the project changes, the change is decided and recorded rather than drifted into and forgotten.

The review will have stung a little. It is supposed to. Somebody spent forty-five minutes of their life finding what was wrong with your work, and the correct response to that is not defense — it is gratitude, and then rework on Saturday. Faithful are the wounds of a friend. You will get a great many of these in your career, from code reviewers and architects and users and, eventually, from production at three in the morning, which reviews without gentleness. The engineers who get good fastest are the ones who learned early that the person finding their mistakes is on their side.

Now go cut the scope you know you need to cut. Do it this week, while it costs twenty minutes. The arguing is over. On Monday, we build.

See you on Monday.

Up next: the exercises is this week’s graded Design Review lab, twelve reps and a hundred-point rubric — there is no Milestone 8 · then Chapter 9, where construction begins and one real request travels the whole system end to end. Reference appendices: Appendix A (your workbench), Appendix B (the document kit), Appendix C (the grading contract), Appendix E (glossary). Previous: Chapter 7.