Chapter 4 — The Design Review and the Halfway Truth

“More software projects have gone awry for lack of calendar time than for all other causes combined.” — Fred Brooks, The Mythical Man-Month (1975)

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

Why This Matters

Halfway. Eighty of your one hundred sixty hours are gone, and this is the week you find out what they bought.

Behind you are three weeks of deciding: a charter, a project adopted from a brief and adapted until it was yours, a requirements specification with measurable non-functional requirements, architecture decision records, a technical specification, a plan, a risk register, and a walking skeleton that carries one real request end to end under continuous integration. Ahead of you are four weeks of building and shipping. This week is the hinge, and it is the only week of the course with no new document to invent.

The hat you wear 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, including you, can reconstruct in Week 8 what you decided in Week 3. In industry this week has a name, the design review, and it survives in every kind of software organization for one unglamorous, provable reason: 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.

Then you will do something that feels like the opposite of moving fast and is not. You will freeze the specification into a baseline, and everything that changes from here changes through a written change request — not because paperwork is virtuous, but because in Week 7, at eleven at night, when 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.

And then the halfway truth, which is why this chapter has the title it has. You will put your logged hours next to your completed Must requirements, project both to Week 8, and find out whether the plan you wrote in Week 3 can be built by the person your log says you are. For most of you it cannot, by somewhere between ten and thirty hours. That is not a failure — it is the expected result, and it is the most valuable thing this course can hand you while there is still time to act on it. Which brings back the rule you have heard since Week 1: 160 hours buys a project about two-thirds the size of a sixteen-week capstone. Three or four Must features, not five or more. If your Must set is still five deep, this is the week it stops being five.

The AI thread runs from both sides, and it matters more here than anywhere. As a tool, an assistant is a genuinely strong first-pass reviewer: it will read your requirements against your technical specification and find the six requirements you never designed for, faster than a human could and without getting bored. As an accountability problem, it is a reviewer that has never shipped anything, has no stake in whether you finish, and will hand you confident, well-formatted findings — some wrong, a few citing section numbers that do not exist. Every finding it produces enters your defect log marked unverified. The spine rule holds: the assistant accelerates the search, you decide what is a defect, and you sign the report.

So the apologetic question, which is older than engineering: why do we need other eyes? Not “why is peer review a nice idea,” but why can a person — competent, careful, honest, working hard — not reliably see what is wrong with their own work? That is a claim about what a human being is, and everything about how you run this week depends on the answer.

4.1 — Reviews Find Defects Testing Never Will

Testing and reviewing are not two ways of doing the same job. They reach different defects, and the ones review reaches are the expensive ones.

A test is a comparison between behavior and an expectation. If the expectation comes from the specification and the specification is wrong, the test agrees with the bug. Every green check in your pipeline is a statement about consistency, not correctness.

Look at rows three through seven. Those are the defects that end accelerated capstones, and none is reachable by any test you could write, because a test cannot notice an absence. A test asks whether the code matches the plan. A review asks whether the plan is any good.

The second reason is economic. A defect found in a requirements sentence costs a rewritten sentence; the same defect found in Week 7 costs a rewritten module, its tests, its documentation, and hours you no longer have. You do not need a precise multiplier — the direction has been reported consistently across the software-engineering literature since Barry Boehm’s cost-of-change work in the early 1980s. In eight weeks the multiplier is worse than in sixteen, for a reason that is pure arithmetic: a week here is an eighth of the term. Falling behind is proportionally twice as expensive as in the long edition, and there is no October in which to recover.

Know the lineage 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 distinguishes the family: a management review checks progress, a technical review evaluates fitness for purpose, an inspection is the formal defect hunt with defined roles, a walkthrough is the author-led lighter version, 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 a single 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.

4.2 — Author, Moderator, Reader, Recorder: Faking 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 descending order of what it buys you.

1. Recruit one human being. Not optional in spirit. An advisor, a classmate, a working engineer, the stakeholder you interviewed in Week 1. Give them the package, the checklist in code/design-review-checklist.md, a 45-minute box, and a specific charge. One outside reader finds what no technique below will find, because they do not know what you meant.

2. Separate the roles in time, since you cannot separate them in people. Author on Sunday, Reader on Tuesday. Students in a compressed course skip this because forty-eight hours sounds expensive. It is not: the gap costs calendar, not hours, and calendar is the one resource this week has plenty of. Do the walkthrough cold or do not bother.

3. Be the Reader out loud, and change the medium. Read docs/architecture.md 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. Then print it, or read it on a phone, or change the font: your eye skips what it has already parsed, which is why proofreaders read backwards.

4. Let the checklist and a named persona be your proxy reviewers. A checklist is other people’s memory of what goes wrong, compressed; every line in code/design-review-checklist.md is there because somebody’s project died for want of it. And do not ask “would this be clear?” — clear to whom? Read it as the engineer who inherits this in January, as the grader with forty minutes for your repository, as the exhausted version of you in Week 7. Each persona finds different holes. Then, and only then, use an assistant as a third reviewer — section 4.8.

The package, and the brief that makes it worth reading

A reviewer’s time is the scarcest thing in your week. The package is how you refuse to waste it: six artifacts, one running system, and one page of instructions.

1. docs/requirements.md with the Must set marked, functional and non-functional (Week 2).
2. docs/definition-of-done.md (Week 2).
3. docs/adr/ — the decision records (Week 3).
4. docs/architecture.md with its diagrams (Week 3).
5. docs/plan.md and docs/risk-register.md (Week 3).
6. docs/hours-log.csv, current through this week (Week 1 onward).
7. The walking skeleton itself — a link to the green CI run and the output of script/smoke.

That seventh item is unique to this edition and it is a real advantage. The sixteen-week course reviews a design with nothing built; you are reviewing a design with one request already travelling the whole system. It changes the question you can ask a reviewer from “does this sound right?” to “which hop would you be most nervous to build next?” — and people answer the second question much better than the first.

Then the reviewer’s brief, one page at the front. Students skip it, and it is the part that decides whether the review is useful. A bad one reads “Hey — attached is my capstone design doc. Any feedback welcome!”, which guarantees comments on your font: “any feedback welcome” outsources the decision of what matters to somebody who knows less about your project than you do, and people who do not know what is wanted default to the safest criticism, which is cosmetic. A good one:

Design review: PantryPilot (adapted from Fast-Start brief #1 for a 12-person
co-op kitchen), accelerated senior capstone, baseline gate.

What I need (45 minutes, please do not go over):
  1. docs/requirements.md section 5 (the Must set, 6 requirements) and
     docs/architecture.md sections 3-4 (interfaces, data model).
  2. Use docs/review/design-review-checklist.md, Area 0 and Areas 1-3.
  3. I am specifically asking two things: (a) does any requirement still
     describe the BRIEF's household of four rather than my co-op, and
     (b) is there a Must requirement this design does not satisfy?

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 9c14ba2. CI green.
Time box: 45 minutes reading, 45 minutes together Thursday.

That brief bounds the reading, names the checklist, names the two questions, 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. Then apply the entry criteria: in a formal inspection the moderator refuses the meeting if the package is not ready, so be that moderator to yourself. No load-bearing TBDs, no whiteboard photographs standing in for diagrams, CI green at the reviewed commit, and a package a person can finish in forty-five minutes. Respect the rate limit too — the widely cited SmartBear analysis of peer review at Cisco reported that defect-finding effectiveness fell off sharply past roughly an hour in a sitting. Treat the number as indicative and the shape as certain: attention is a consumable.

Coach’s Note — If you do only one thing from this section, 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.

4.3 — 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 designing the fix — the highest-status and most fun activity in engineering — and it is not coming back. You will spend thirty minutes on the first problem you found and never open section 4, where the real one was.

The bad walkthrough:

Reviewer: In section 4.2, quantity is an integer, but FR-007 talks about half a bag of flour. Author: Oh — yeah. I could make it a float? … But units vary. Grams for flour, count for eggs. Does the lookup API return units?

— twenty-two minutes later they have designed a unit-conversion subsystem, logged zero defects, and never reached the section where the failed-write path silently loses data.

The good walkthrough:

Reviewer: In section 4.2, quantity is an integer, but FR-007 talks about half a bag of flour. Author (recording): Got it. DR-004, docs/architecture.md 4.2, quantity type cannot satisfy FR-007. Major. Moving on — section 4.3. Reviewer: You could store it in grams — Author: Logged. I will decide that on Saturday. Section 4.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.” When you run the review alone, you are the moderator, and the person you must interrupt is yourself — which is hard, because 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 Saturday is for. Two rules follow from the same principle. Findings are about the document, not the author — “section 4.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 gets remembered. And every finding gets a location: a finding without a section number is a mood, and the recorder’s job is to refuse it.

Severity and disposition are different axes

The review produces a list, and the list is worth nothing until every item has been dispositioned — decided, in writing, by the author. Students merge two things that must stay separate: severity is how bad it is if it ships; disposition is what you are going to do about it. A Minor can be fixed today; a Critical can be deferred if you write down why.

Disposition is one of five, every one requiring a written reason: Fix now, Deferred (raise a change request and give it a week), Rejected — not a defect (write why; this is the one people skip and the one that protects you, because in three weeks you will not remember why you ignored it), Duplicate of finding X, or Accepted risk (you know, you are proceeding, and it goes in the register with an owner).

A bad log row reads 3 | data model | wrong types | high | will fix — six words, all useless in a month. Here is a good one, from code/review-defect-log.csv:

DR-004 | self | walkthrough | data-model | docs/architecture.md 4.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 changed to decimal plus a unit field; spec section rewritten" | me | 4 | yes

That row is a complete unit of accountability: who found it, how, where, which requirement it threatens, how bad, what you decided, what you did, who owns it, when it is due, whether it was verified. Sixteen of those rows are a review report. Copy the template with its worked rows to docs/review/defect-log.csv — in Week 6 it grows up into docs/defect-log.md for the running system, with the same columns. And keep verification separate from fixing: “fixed” means you changed something, “verified” means somebody checked that the change resolves the finding and did not create a new one. 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.

At the end the moderator records one of three outcomes. This is the actual gate.

4.4 — 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 serves as the basis for the work, and that may be changed only through a defined procedure. 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 looked, decided, and are 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 “freeze the spec” makes students think waterfall. Agile teams baseline constantly — they call it a sprint commitment, a definition of ready, a merged 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 its existence. 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. Rework committed, review report in the repo.
git add docs/ && git commit -m "docs: rework DR-001..DR-016 from the Week 4 design review"

# 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-10-03, accept with rework"
git push origin spec-baseline-v1.0

# 3. Write the declaration: docs/baseline.md

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 tag, the review report, the Must set as it now stands with its estimate, and — the part people forget — the open items carried past the baseline, so a deferred defect does not quietly become a forgotten one. Note what is not on the list: the walking skeleton. Code is never in a specification baseline; the documents that describe it are.

A bad baseline is “I finished the spec” — no tag, no declaration, no report, and the document keeps changing silently for four weeks, until in Week 8 the specification describes a system that was never built and nobody, including its author, can say when it diverged. A good baseline is a tag, a commit SHA, and a one-page declaration listing eight frozen artifacts and two carried-open defects, after which every change to those eight arrives with a change-request id in the commit message. In Week 8 you run git diff spec-baseline-v1.0 -- docs/ and see, on one screen, everything your project learned in four weeks — and that diff is half 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, and faster than they expect.

4.5 — Change Control From Here to Week 8

The specification will change. Of course it will — you are about to learn things by building. Change control does not prevent change; it makes change decided rather than drifted into.

Two failure modes, and they look nothing alike. Scope creep by accretion: no single addition is unreasonable — a small filter in Week 5, QR codes as well as barcodes in Week 6, a settings page in Week 7 because it is only an hour — and by Week 8 the Must set has grown a third, 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 6 offline mode turns out to be hard, so you quietly stop working on it. Nobody decides anything. In Week 8 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 6 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. Say it 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 three hours.
4. Changes the stack.
5. Changes the definition of done.

Three hours, not the sixteen-week edition’s four — because three hours is a seventh of your week here, and a change that size deserves a paragraph. 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 be ignored by its only participant, which is worse than no process.

A bad change is a text to a friend — “dropping the barcode scanner, it’s too hard” — and nothing in the repository: fourteen hours of plan vanish and reappear as unexplained slack, and in Week 8 the requirement is still marked Must. A good change is docs/change-requests/CR-001-cut-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 during the Week-3 skeleton), the impact (FR-016 and NFR-07 affected; minus fourteen hours; risk R-04 closes; WP-6 removed), the decision (approved after a ten-minute conversation with the instructor, because a Must requirement is moving), and the applied checklist. Twenty-five lines that convert a retreat into a decision. Who decides? In industry, a change control board. Here you are the board — with one exception you must honor: moving a Must requirement out of scope is a conversation with your instructor, not a private edit. It affects your grade, and two minutes in Week 4 is much cheaper than a surprise in Week 8.

4.6 — The Halfway Audit: Hours Spent Against Musts Completed

Now the honest part. Two numbers, side by side, and the projection they imply.

Half the budget is gone. Eighty of one hundred sixty hours, and the application does not exist yet — a skeleton walks, and that is all. That is on purpose: the first half converted the hours that remain from discovery into construction, and the most expensive hour in software is the one spent building something before you knew what it was. But read the remaining eighty carefully, because it is a course budget, not a project budget. In Week 3 you did this subtraction once and wrote 53.2 plannable hours at the top of docs/plan.md. That line covered Weeks 4 through 8. Week 4 is now being spent, so run it again for the four weeks that are actually left — code/halfway-audit.py against docs/hours-log.csv does it for you, off the same capacity table:

WHAT IS ACTUALLY LEFT (weeks 5-8)
  course hours remaining              :    80.0
  less course overhead                :   -20.0
  = project hours                     :    60.0
  less declared 25% buffer            :   -15.0
  = PLANNABLE hours                   :    45.0
  less test, docs, deploy, handoff    :   -18.0
  = hours available to BUILD FEATURES :    27.0

Forty-five plannable hours, and inside them twenty-seven hours of feature construction. Read the second number twice, because it is smaller than every student expects and it is the true number your Must set has to fit inside. (Run the tool with --through 3 and it reproduces the 71.0 and 53.2 you wrote in Week 3, so you can see that nothing moved except the calendar.) The rule I will commit to: if your remaining plan estimates above 45 hours, or the Must set alone above roughly 27, you cut this week. Check it against the two-thirds rule, because the arithmetic is not a coincidence. The sixteen-week edition runs the same subtraction at its own halfway point and lands on about 65 plannable hours and about 40 for the build. Yours are 45 and 27 — right around two-thirds, which is why the rule is stated the way it is, and why a five-Must plan that would merely be tight in the long edition is simply impossible in this one.

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

1. Hours. What does your log actually say? Run the audit and read the variance line. Not the number you remember — the number you logged.
2. Scope against what is left. Add up your plan’s estimates for the Must set only and compare it to 27. Pass --must-estimate and --musts and let the tool tell you how many requirements have to move.
3. Musts completed. How many Must requirements are done by your own definition of done? At Week 4 the honest answer is usually zero, and that is fine — but if it is zero and your remaining Must estimate is 47 hours, the projection has already decided something for you.
4. Risk. Has any trigger already fired? Read the register and check them one at a time. A risk you wrote down in Week 3 and never looked at again is a wish.
5. Environment and novelty. Push a trivial commit and confirm CI is still green. Then count the planned tasks that are things you have never done — each is an estimate you cannot trust and a spike you should schedule, and in four weeks you can afford about one.
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 1 — the first 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 1, 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. In eight weeks this is the last cheap moment to act on it.

Coach’s Note — The failure mode to name and refuse: passing the audit by adjusting the budget instead of the scope. “I’ll do thirty hours a week in the back half” is not a plan; it is a hope with a number attached, and you have four 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.

4.7 — Cutting Scope in Week 4 Is Competence, Not Failure

The cheapest scope cut in the entire course is the one you make this week, because almost nothing has been built on top of it. A requirement removed today costs the twenty minutes to write CR-001. The same requirement removed in Week 7 costs the hours you already spent on it, plus the hours to rip it out, plus the documentation that now lies, plus the test that now fails.

Here is what the tool says when the plan does not fit:

THE CUT ARITHMETIC
  Must-set estimate from docs/plan.md :    47.0 h
  hours available to build features   :    27.0 h
  variance                            :   -20.0 h  -- IT DOES NOT FIT.
  Must requirements in the set        : 6
  Musts that must move out of v1      : 3  (leaves 3, est. 23.5 h)

That “3” is a crude average — the tool divides the estimate evenly across the set. You will usually beat it, because you cut the expensive requirements, not the average ones: dropping a 14-hour offline mode and a 9-hour shopping list takes 23 hours out and leaves four Musts at 24, which fits inside 27. Cut in this order, and cut the whole requirement, never half of it:

Cut last: whatever makes the Week-8 demo tell a coherent story end to end. Three features that work completely and demo in four minutes beat six features at eighty percent — every time, on every rubric, in every job interview. Two rules about how to cut. Move it, do not delete it — a cut requirement goes to the out-of-scope list with a one-line reason and a note in the eventual handoff guide, which is the difference between a scoped project and an abandoned one. And demote whole, not partial — half of FR-016 is not a feature; it is a half-built thing that still costs test time, documentation, and an apology in the presentation.

Coach’s Note — Nobody has ever regretted cutting scope in Week 4. Hundreds of students have regretted not cutting it. When you write CR-001 this week you are not admitting you were wrong in Week 2 — you are demonstrating the most valuable engineering habit there is: changing the plan on evidence, in public, in writing.

4.8 — The Adversarial AI Pass, and the Findings It Will Never Make

An assistant is the best first reviewer available to you 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 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”), unhappy-path coverage (“for each endpoint in section 3, list the error conditions the specification does not describe”), and measurability (“which non-functional requirements lack a metric, threshold, condition, or method?”). The single best prompt is the absence question: “What does this specification not say that a developer building it in twenty-seven 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 ONE student
must finish in about 27 hours of feature construction. 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] [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-012 and DR-013 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 wrong out of five tells you how hard to squint at the next batch.
• It cannot see the adaptation drift, which is your worst defect class. It has no idea that FR-013 describes the brief’s household of four while your users are twelve residents of a co-op kitchen. Both sentences are internally consistent and well-formed. Only somebody who knows your actual project can catch that, which is why Area 0 of the checklist is a human pass.
• It cannot see your velocity. It does not know you have logged 13.2 hours a week against a budget of 20, or which technologies you have never touched. It will bless a plan that cannot be built by you.
• It agrees. Ask “is this a good design?” and you get an encouraging graded answer, because helpfulness is what it optimizes. Adversarial framing helps; it does not cure.

The rule for the week, and it is not negotiable: every assistant finding enters the log with source: ai pass and verified: no, and closes only when you open the actual document and look. 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. Hunt for: numbers that sound authoritative but trace to nothing (“shall respond within 200ms” — says who?); requirements that restate their own heading; error handling that says “handle errors gracefully”; interfaces with a verb and a path but no payload; paragraphs that are perfectly organized and say nothing you could build from. And the courtesy rule: never spend a human reviewer’s forty-five minutes on a document you have not self-reviewed.

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

4.9 — Interactive Lab: The Halfway Audit

Below this chapter on the website is The Halfway Audit. Use it after you have assembled your package and before you sit down with your human reviewer. It puts the review checklist and the pace verdict in one instrument, because in an eight-week course they are the same conversation.

You will answer evidence-backed review questions across the six areas of code/design-review-checklist.md — requirements traceable, interfaces specified, data model sound, risks owned, definition of done written, skeleton walking. Each item is yes, no, or partial, and each answer wants a short evidence note: a section number, a requirement id, a table row, a commit SHA. An item marked “yes” with 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.

Then you enter the two numbers that make this an accelerated course’s review rather than a generic one: hours spent to date and Must requirements completed to date. The Audit returns three things. A readiness score — a temperature, not a grade. A prioritized list of what a real reviewer would send back, ordered so the top item is the one that would block your baseline. And a projection to Week 8 — where your logged pace and your remaining Must estimate actually land — with the specific cut list that brings the plan back inside 160 hours when the projection overruns. 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 certain they had specified exist only in their head. Better to find that in an afternoon in Week 4 than at the keyboard in Week 7. Export the seeded defect rows and merge them into docs/review/defect-log.csv so they enter the same accountable pipeline as the human findings.

4.10 — The Midterm Checkpoint and What It Is Really Measuring

This week’s quiz is the midterm checkpoint: auto-graded, cumulative over Weeks 1–4, and one of the eight weekly quizzes that make up 15% of your grade. It is longer than a normal week’s because it covers half a course of vocabulary — the language of the software development life cycle, which you will be expected to speak in every interview you take this spring.

But the checkpoint is not really measuring vocabulary, and you should know what it is measuring so you can pass the real test. It is measuring whether the first half of an accelerated capstone produced a project you can finish. 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. The full contract, including how the eight quizzes are weighted, is in Appendix D.

4.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 meets this experimentally. You proofread a document five times, ship it, and the first reader 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 — 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 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 psalmist asks the exact question this 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 the design review’s problem statement, written three thousand years before Fagan wrote his. And 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 I make is any good, 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. Luther’s picture of vocation is exactly this: God ordinarily provides through ordinary people doing ordinary work — the farmer, the magistrate, the neighbor, and yes, the classmate who spends forty-five minutes on your interface section. They are masks through which God works. Your reviewer is not an obstacle between you and your grade. They are a gift with a schedule conflict. And there is an accelerated temptation here worth naming, because it will come for you specifically: when the term is eight weeks long, counsel feels like a luxury you cannot afford — it costs a day of calendar and forty-five minutes of somebody’s goodwill, and you have code to write. That instinct is exactly backwards, and section 4.6 says so in arithmetic. The defect a reviewer finds this week costs a sentence; the same defect found in Week 7 costs a week you do not have. Compression is a reason to seek counsel harder, not a reason to skip it. The proverb has no exemption clause for people who are busy.

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 adds, tellingly, “Keep watch on yourself, lest you too be tempted” (Galatians 6:1, ESV). The reviewer who enjoys it has lost the thread. Specific, located, about the document, delivered without contempt: that is not only 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 4.2, no units; FR-011, unverifiable; the plan is twenty-one 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. Students who cannot receive criticism have almost always 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.

4.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 hand over the checklist. If a review produces zero findings, the review failed; it did not pass.

Pitfall: Skipping the adaptation sweep because the requirements “were already reviewed in Week 2.” Example: FR-013’s acceptance criteria still say “the household of four,” which is the Fast-Start brief’s user, not your twelve-resident co-op. It survives to Week 7, gets built, and satisfies nobody. Fix: Run Area 0 of code/design-review-checklist.md before anything else, and grep your documents for the brief’s project name. An inherited requirement that quietly describes somebody else’s project is the signature failure of this edition.

Pitfall: Fixing in the room. Example: The first finding turns into a twenty-minute design session for a unit-conversion subsystem, and section 4 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: Findings collected but never dispositioned, and a baseline that is not actually baselined. Example: Sixteen findings in a note, none decided; “the spec is done” with no tag, no SHA, no declaration — then four 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. 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 8.

Pitfall: Treating an assistant’s finding as a fact. Example: Rewriting section 4 because a model said the schema 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 closes only when you open the document and look. 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, or cutting without telling the requirements document. Example: The Must set estimates at 47 hours, 27 are buildable, so the plan becomes “I’ll just do thirty hours a week from here” — or you decide on Saturday to drop offline mode and docs/requirements.md still marks FR-016 Must in Week 8. Fix: Estimate with the velocity your log proves you have. Then make the cut real: a change request, a moved priority, an out-of-scope line with a reason, and a row in CHANGELOG.md. Twenty-five lines, the same day.

4.13 — Where Your Hours Went This Week

Twenty hours, and the shape 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 6 a number it can trust.

4.14 — Reps: This Week’s Graded Work

There is no Milestone 4. This week has no new document to produce, because the work is to test the documents you already have. The reps in the exercises are this week’s graded lab — ten of them, carrying their own hundred-point rubric, walking the whole review from package to baseline to cut list. Preview:

• Rep 2 — the adaptation sweep: every Must checked against your project, not the brief’s.
• Rep 4 — the solo walkthrough, cold and out loud, forty-eight hours after you last edited.
• Rep 6 — forty-five minutes with one actual human being, logging what they say without arguing.
• Rep 10 — run code/halfway-audit.py, write the cut list, and raise CR-001.

Like every milestone in this course the lab is paid for twice — it feeds the milestone bucket, and what it produces is exactly what the Week-8 rubric pays for again: a baselined specification, a defect log with dispositions, a signed review report, and change control with a real change in it. Skipping it does not save you the points. It defers them to a week with no time left. (Appendix D has the full contract; Appendix C has a worked example of every artifact.)

Do the on-page Check Your Reps quiz when you finish the chapter, then go to the lab.

4.15 — Coach’s Final Word

Three weeks ago you adopted a brief. Today you have a specification that has been read by somebody who is not you, a list of the things that were wrong with it, a written decision on every one, a scope that fits the hours you actually work, 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 barely written any. The tag. It means a version of the truth 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 is not defense — it is gratitude, and then rework on Saturday. Faithful are the wounds of a friend. You will get 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 cut the scope you already know you need to cut. Do it this week, while it costs twenty minutes and a paragraph. Four features that work completely will beat six at eighty percent in front of every audience you will ever face. The arguing is over. On Monday, we build.

See you on Monday.

Up next: the exercises is this week’s graded Design Review and Halfway Audit lab — ten reps and a hundred-point rubric; there is no Milestone 4 · then the midterm checkpoint quiz on the course site · then Chapter 5, where construction starts against exactly what your baseline tag says. Reference: Appendix A (your workbench), Appendix B (the Fast-Start Catalog), Appendix C (the Document Kit), Appendix D (the Grading Contract), Appendix E (glossary). Previous: Chapter 3.