Chapter 4 — Reps: The Design Review and Halfway Audit Lab

There is no Milestone 4. These ten reps are this week’s graded work — the full review, from assembling the package to declaring the baseline to cutting the scope your own numbers say you cannot carry. Work them in order; each one feeds the next.

Ground rules

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

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

Block A — Prepare the package (Monday–Tuesday)

Rep 1 — Assemble the package and gate it yourself

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

# Six artifacts, six paths. Your Week-2 NFRs live inside docs/requirements.md.
ls docs/requirements.md docs/definition-of-done.md docs/adr/ \
   docs/architecture.md docs/plan.md docs/risk-register.md docs/hours-log.csv

# The seventh item is the skeleton. Prove it still walks, today.
./script/test && ./script/smoke

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

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

Write: three sentences naming what you had to fix to pass your own entry criteria, and paste the URL of the green CI run at the reviewed commit. If the answer to the first is “nothing,” you did not look hard enough.

Rep 2 — The adaptation sweep: is this still your project?

This is the rep that exists only in the accelerated edition, and it is worth the most points. You started from a Fast-Start brief in Appendix B and inherited somebody else’s sentences. Some of them are still describing somebody else’s project.

Run Area 0 of the checklist over every requirement in your Must set and every non-functional requirement. Then run this, and read every hit:

# The brief's project name, its named user, and its numbers should not survive.
grep -rniE "pantrypilot|household of four|roommate" docs/ | grep -v "adapted from"

# Every number in an acceptance criterion: can you say where it came from?
grep -rnE "[0-9]+ (items|users|seconds|ms|records|rows)" docs/requirements.md

Fill in one row per Must requirement and per NFR:

Anything marked inherited or unjustified is at minimum a Major defect. Log it with the location and the exact sentence.

Write: the completed table plus one paragraph: what did the brief assume about its user that is not true about yours? Everyone has at least one. The students who claim zero are the ones who find four in Week 7.

Rep 3 — The traceability spot-check and the reviewer’s brief

First, trace. For every Must requirement — all of them, there should only be four to six — record what you actually find:

An orphan is a requirement with no design, no task, or no test — a promise with nothing behind it, and a Major at minimum. Then run it backwards: find one component in docs/architecture.md that traces to no requirement. That is gold plating, and it is hours you were about to spend for free.

Then write the brief. One page, at the front of the package, containing all five moves from section 4.2 of Chapter 4: bound the reading, name the checklist areas, name the question you most want answered, rule things out, pin the tag and the time box. Commit it as docs/review/reviewer-brief.md.

Write: the traceability table, the gold-plated component, and the brief itself. Read the brief back and ask whether a competent stranger could start reading in under two minutes. If not, cut it in half.

Block B — Run the review (Wednesday–Thursday)

Rep 4 — The solo walkthrough, cold and out loud

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

Use at least two amplifiers: a different device or print; a text-to-speech reader; a named persona (the engineer who inherits this in January and has never met you).

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

Produce: at least six located findings in the log format. Write: the one sentence you had to explain out loud that surprised you most.

Rep 5 — Run The Halfway Audit

Open The Halfway Audit on the chapter page. Work all six areas — requirements traceable, interfaces specified, data model sound, risks owned, definition of done written, skeleton walking — answering yes / no / partial with a real evidence note on every item. Then enter your two numbers: hours logged to date and Must requirements completed to date.

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

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

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

Rep 6 — Forty-five minutes with one human being

Send the package and the brief to one actual person: an advisor, a classmate, a working engineer, or the stakeholder you interviewed in Week 1. Give them the checklist and a 45-minute box. Then sit with them.

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

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

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

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

Rep 7 — The adversarial AI pass, then the verification

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

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

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

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

Block C — Disposition and rework (Friday–Saturday)

Rep 8 — Severity, disposition, rework, verify

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

Two rules that are graded. Every rejection needs a written reason — “Rejected — not a defect” with an empty reason column is worth zero. And severity and disposition are independent: a Major can be deferred if you say why and raise a change request; a Minor can be fixed today.

Then fix every Critical and every Major marked Fix now, with the ids in the commit message:

git commit -m "docs: rework DR-001, DR-003, DR-008 from the Week 4 design review"

On a different day, verify: reopen the original finding text — not your memory of it — and confirm the change resolves it without creating a new problem. Set verified to yes and record the date. Fixed is not verified.

Write: the counts by severity, the one disposition you are least comfortable with, and one finding whose fix created a second finding. There is usually one, and catching it is the whole point of verifying separately.

Rep 9 — Declare the baseline and stand up change control

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

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

Write docs/baseline.md naming every frozen artifact with its repo path and version, the commit SHA, the tag, the review report, the Must set as it now stands with its total estimate, and the open items carried past the baseline so a deferred defect does not become a forgotten one. Remember what is not frozen: the walking skeleton. Code is never in a specification baseline.

Then create docs/change-requests/, copy the change-request template in, and add the change table to the top of CHANGELOG.md.

Write: three sentences on what is now frozen and what is deliberately not, addressed to the engineer who will read this in Week 8. Then the threshold rule in your own words — the five kinds of change that need a change request for the rest of this course, and one kind that deliberately will not.

Block D — The halfway truth (Saturday)

Rep 10 — The audit, the cut list, and CR-001

Run the audit against your real log, with your real plan numbers:

python3 halfway-audit.py --demo                       # see a worked example first
python3 halfway-audit.py docs/hours-log.csv --through 4 \
        --must-estimate <your plan's Must-set hours> --musts <how many Musts>

Answer the seven questions from section 4.6 in writing, each with evidence: hours logged versus budgeted and the trend; scope — your Must-set estimate against the ~27 buildable hours the tool computes; Musts completed to date by your own definition of done; risk — which triggers you actually checked this week and what you found; environment and novelty — push a trivial commit, confirm CI is green, and count the planned tasks you have never done before; the user — is your stakeholder still answering?; and the cut order — open docs/scoping-decision.md, say in writing whether the trigger you pre-committed in Week 1 has fired and whether the order is still right, and cut today if it has.

Then build the cut list. If the projection overruns, name the requirements that come out, in the order given in section 4.7, and raise CR-001 in docs/change-requests/ with every field filled in, including the ones that hurt: requirements affected by id, hours removed, the Must set after the change, schedule effect, risk effect, decision, and rationale. Write the rationale even though you are approving your own request. Especially then. If a Must requirement is moving, that is a ten-minute conversation with your instructor, not a private edit.

Produce: docs/review/week-04-audit.md, using the template in code/baseline-and-change-control.md. Write: the paragraph. Not the numbers — the paragraph that says what you are changing because of them. “I have logged 53 of 80 hours, my Must set estimates at 47 against 27 buildable, so CR-001 moves offline mode and the shared shopping list out of v1 and my Must set is now four requirements at 24 hours” is an audit. “I need to work harder” is a wish.

Done? One Last Thing.

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

In this order:

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

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

Normal-tier rubric (out of 100)

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

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

Up next: the midterm checkpoint quiz on the course site — auto-graded, cumulative over Weeks 1–4; study from the table in section 4.10 of Chapter 4. Then Chapter 5, where the arguing stops and you build the core against exactly what your baseline tag says. Reference: Appendix B (the Fast-Start Catalog), Appendix C (the Document Kit), Appendix D (the Grading Contract), Appendix E (glossary).