Chapter 16 — Reps

These are not warm-ups. Worked in order, top to bottom, they are Milestone 16 — the audit, the proof, the release, and the close-out. Eleven reps, one week, fifty percent of a course.

Ground rules

• Every rep runs against a fresh clone, never your working directory. The number of capstones that lose points because the crucial file was untracked on the author’s desktop is not small.
• Write the evidence before you tick the box. A checkbox ticked from memory is a lie you are telling yourself on the most expensive day of the semester.
• Feature freeze is in force from Rep 1. After the freeze, three kinds of commit only: documentation, a fix for something an audit found, the change log.
• Score honestly. A self-audit that returns 100/100 is not an audit, it is a mood. The whole value is finding the cheapest points still on the table while there is still time to take them.
• Log the hours. Yes, this week too. It is the last row of a sixteen-row table and it should be as true as the first.
• Everything you need is in code/final-submission-checklist.md, code/clean-machine-test.sh, code/secret-scan.sh, and code/retrospective-template.md. Templates and worked good/bad examples for every artifact are in Appendix B.

Block A — Audit

Rep 1 — Clone your own tag and look at what is actually there

Freeze, push everything, then clone the tag you currently intend to submit into a directory you have never worked in.

git status                      # must be clean; commit or stash anything left
git push origin main
git clone --branch <current-tag> --depth 1 https://github.com/<you>/<repo> /tmp/selfaudit
cd /tmp/selfaudit && ls -R docs && ls -la

Now, without opening a single file, write down the inventory: which of the twelve required artifacts exist as files, and which do not.

Produce: a two-column list — present and absent — for all twelve artifacts.

Reflect (100 words): How many were absent from the clone that you believed were done? For each, where was it actually living — untracked, on a branch, in a comment, or only in your head? That gap is the single most common way capstone points are lost, and you just measured yours.

Rep 2 — Score all twelve rubric lines with defensible evidence

Open code/final-submission-checklist.md and fill the evidence table from the clone. For each line: the path, a one-line evidence note a grader could verify in under a minute, and the score you would defend to a stranger.

The standard for an evidence note:

WEAK:  "Requirements: yes, they're in docs/requirements.md. Complete."

REAL:  "docs/requirements.md §3 has FR-01..FR-23, each with a MoSCoW priority
        and 1-3 Given/When/Then acceptance criteria; §4 has NFR-01..NFR-09 with
        a number and a measurement method each; §6 traces every FR to at least
        one test case ID. FR-14 and FR-19 are marked deferred with issue links."

Produce: twelve evidence notes and twelve scores, summing to your projected total out of 100.

Reflect (150 words): Which line was hardest to write an evidence note for? In my experience that line is the one that is genuinely weakest — writing the proof is what exposes the gap. Was that true for you?

Rep 3 — Triage by points-per-hour, not by irritation

Take every gap from Rep 2 and rank it. Two columns only: points at stake and honest hours to close. Then divide.

Produce: the ranked table, and a line drawn across it marking where your available hours run out.

Reflect (100 words): What is below your line, and are you at peace with it? Name the one thing you are choosing not to fix and why that is the right call. Choosing deliberately is engineering; running out of time by accident is not.

Block B — Prove it

Rep 4 — The hostile read, then the verification

Paste your entire README into an assistant with a role and a stopping condition:

You are a competent developer who has never seen this project and has thirty
minutes. Follow this README literally, step by step. At the first instruction
you could not execute without guessing something, stop and tell me: which line,
what you would have had to guess, and what you would have tried next. Do not be
encouraging. Do not fill in anything the document does not say.

Run it four times with four personas: default, Windows, no admin rights, never used your package manager.

Then — and this is the rep — verify every finding against the actual repository. The model is reading prose, not executing it; it cannot tell you whether your commands work, and it will cheerfully call a broken quickstart clear.

Produce: a table of findings with three columns — finding, real or false alarm, fix applied.

Reflect (150 words): Which findings did you want to dismiss because the answer was “obvious”? Write down what was obvious to you and why it is not obvious to anyone else. Every objection dismissed this week is a deduction on Friday.

Rep 5 — The clean-machine test, live, and you do not speak

A human who is not you. A machine that is not yours. Your README and nothing else.

bash clean-machine-test.sh https://github.com/<you>/<repo> <tag> "Sam (Windows, roommate)"

The harness clones the tag into a throwaway directory, times the attempt, prompts for the four measures, and writes a report. Your job during the attempt is to sit behind your tester with a notebook and say nothing — not a hint, not a correction, not a sympathetic noise.

Produce: the generated report pasted into docs/test-results.md, plus your notebook page: every question asked, every guess made, every file other than the README they had to open.

Reflect (150 words): How many minutes to a running system? How many times did you have to bite your tongue? Here is the standard, flatly: if a competent stranger cannot run your project from your README in under thirty minutes without talking to you, your project does not run — it runs for you, which is a smaller claim and not the one being graded. Where did you land, and what are you fixing today?

Rep 6 — Sweep the history before you publish

bash secret-scan.sh /tmp/selfaudit

It checks three places: files that should never be tracked, the working tree, and every commit on every branch. Read every hit — it will flag password = process.env.DB_PASSWORD, which is exactly correct code, and a scanner you trust blindly is worse than no scanner at all.

Then check the reverse condition, which is the more common failure: is there a .env.example with placeholder values committed, so a stranger knows which variables exist and what shape they take?

Produce: the scan output, a line per hit saying real-or-placeholder, and — for anything real — the word ROTATED with a date.

Reflect (100 words): Two facts to write in your own words: why deleting a file does not remove it from history, and why rewriting history does not un-leak a key that was already pushed. If you cannot explain both, you are not ready to make anything public.

Block C — Ship it

Rep 7 — Change log, tag, release notes

git add CHANGELOG.md && git commit -m "docs: changelog for v1.0.1"
git push origin main
git tag -a v1.0.1 -m "Capstone final submission"
git push origin v1.0.1
git rev-parse v1.0.1^{commit}

Then write release notes — roughly 150 words, for a human who does not already know what your project is. Not the change log; the change log is for developers and lists everything. Release notes answer should I care, does it work, and what doesn’t.

BAD:  v1.0.1 - Final version. Fixed bugs and updated documentation.
      Everything should work now.

GOOD: v1.0.1 - Capstone submission. <One sentence: what it is and who it's for.>
      Covers all <n> Must requirements (FR-01..FR-09): <list>.
      NOT in this release: <FR-14, deferred, issue #52>; <NFR-05 incomplete,
      tracked as DEF-31, severity Major>. Setup takes about ten minutes; see
      README.md. Verified on a clean machine <date> by a tester who had not
      seen the project.

Produce: the pushed annotated tag, the commit SHA, and published release notes in the good shape.

Reflect (100 words): Why does naming what is missing earn points on three separate rubric lines rather than costing points on one? Answer it in terms of what a grader does with a gap they find themselves.

Rep 8 — The access check and the submission block

The ten seconds that have saved more capstone grades than any other ten seconds in this course: open a logged-out private browser window and paste your repository URL.

Then assemble the block:

Repository:   https://github.com/<owner>/<repo>
Tag:          v1.0.1
Commit SHA:   <40 hex characters>
Access:       public  |  <grader-username> invited and accepted on <date>
Verified on:  <OS/runtime> - clean-machine test <date>, tester <name/initials>
Known gaps:   <open Must requirements by ID, or "none">
Integrity:    <signed statement>

Produce: a screenshot or note confirming the logged-out load succeeded, and the completed block.

Reflect (75 words): Why submit the tag and the SHA rather than a branch name? Answer in one sentence about mutability, then say what you would do if you discovered a critical bug an hour after tagging.

Block D — Close it

Rep 9 — Estimate versus actual, from your own log

Open docs/hours-log.csv and do the arithmetic you have been able to do since Week 1 and have probably been avoiding.

Produce:

• Total planned hours versus total actual.
• Construction (Weeks 9–12) planned versus actual, as a percentage.
• Your three worst single estimates, with task or requirement ID, estimate, actual, and cause.
• One rule, stated with a number in it.

The rule is the whole rep. Not “I should plan better.” Something like: any task that calls an interface I have never personally called before, multiply my estimate by three. Portable, testable, and usable in your first sprint planning at your first job.

Reflect (150 words): What kind of work do you systematically underestimate, and what do the tasks that came in on estimate have in common? Most engineers learn this about themselves around thirty. You are getting it at twenty-two with sixteen weeks of data behind it.

Rep 10 — The retrospective: one remade decision, and the same 240 hours

Fill code/retrospective-template.md into docs/retrospective.md. Two sections carry it.

The decision you would remake. Exactly one, cited to an ADR. What you knew then, what you know now, what you would do instead. Not five decisions — one, examined honestly.

The same 240 hours, spent better. A reallocation table, in hours, where every row cites something in the repository:

BAD:  "I would manage my time better and start earlier."

GOOD: "Cut FR-19 entirely (21 hours, a Should, zero of my three test users
       touched it in the Week 12 demo). Nine of those hours to NFR-05, which
       is a Must and is still failing as DEF-31. The other twelve to Weeks 6
       and 7, where I logged 6 hours instead of 15 - the thin technical spec
       from Week 6 is why Week 10 went sideways."

Produce: the completed docs/retrospective.md, every claim traceable to a file already in the repository.

Reflect (100 words): Read your bad-version instinct and your good version side by side. What made the difference — was it honesty, or was it simply that you went and looked at the logs? (It is almost always the second, which is the encouraging part.)

Rep 11 — The two-minute version, out loud

You are about to own something almost no new graduate has: a complete, documented, defensible project with a link. Rehearse using it.

Four beats, thirty seconds each, spoken aloud on a timer:

1. The problem and who actually had it. (Not the technologies.)
2. The one hard decision and why you made it — the tradeoff, not the preference.
3. What you shipped and how you know it works.
4. What you would do differently, with a number in it.

Then write the résumé line. Problem, scale, evidence, link — never a list of tools.

Produce: the timed recording or a witness’s confirmation, plus one résumé line under 30 words.

Reflect (100 words): Beat 4 is the one that separates candidates, because an engineer who can criticize their own work is an engineer who can be trusted with someone else’s. Was it the hardest beat to say out loud? What does that tell you?

Done? One Last Thing.

Swap links with a classmate and grade each other cold.

Send your repository URL and tag — nothing else, no explanation, no “oh you’ll need to—”. Take theirs. Then, without asking a single question, spend forty-five minutes scoring their submission against the full twelve-line rubric in Milestone 16, writing an evidence note for every line exactly as a grader would.

Then compare their score of you against your self-audit from Rep 2.

Produce: their rubric score of your repository, your score of theirs, and a short delta analysis: every line where you and your peer differed by 2 points or more, and which of you was right.

Reflect (200 words): Where did an outsider score you lower than you scored yourself, and what did they see that you could not? That gap is the exact size of the blind spot you carry into every project you will ever own — and now you have measured it once, on purpose, before it cost you anything. Then fix what they found. You still have time; that is the entire reason this rep exists rather than being the grade itself.

Now go run the auditor one final time, submit before you present, and stand up on Friday and tell the truth about your work for thirty minutes.

You fought the good fight. You finished the race.

Up next: Milestone 16 — Milestone 16, The Final Submission. Fifty percent of the course, and the last thing this book will ask of you.