Chapter 8 — Reps

These are not warm-ups. Worked in order, top to bottom, they are Milestone 8 and the talk that follows it — the audit, the proof, the release, the deck, and the close-out. Twelve reps, twenty hours, fifty percent of a course plus ten.

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 term.
• 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.
• Audit and deck run in parallel. Blocks A and B are the audit; Block C is the talk; they share source material on purpose. If you do Block C last and alone, you will run out of week.
• Score honestly. A self-audit that returns 100/100 is not an audit, it is a mood. The value is finding the cheapest points still on the table while there is time to take them.
• Log the hours. Yes, this week too. It is the last row of an eight-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/retrospective-template.md, and code/talk-kit.md. Templates and worked good/bad versions of every artifact are in Appendix C.

Block A — Audit (Monday–Tuesday)

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 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 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. Each line gets the path, a one-line evidence note a grader could verify in under a minute, and the score you would defend to a stranger.

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

REAL:  "docs/requirements.md §3 has FR-01..FR-12, each with a MoSCoW priority
        and 1-3 Given/When/Then acceptance criteria; §4 has NFR-01..NFR-05 with
        a number and a measurement method each; §6 traces every FR to at least
        one test case ID. FR-07 is marked cut with a link to CR-002."

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 genuinely weakest one — 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, then divide.

Produce: the ranked table, and a line drawn across it 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.

Rep 4 — Hunt the inherited language

This is the rep that belongs to this edition and no other. Open docs/requirements.md, docs/charter.md, and docs/scoping-decision.md, and read every sentence against the software actually running in front of you.

Flag anything that arrived with your Fast-Start brief and never got adapted:

• a persona you never spoke to and never replaced;
• an acceptance-criterion number you never measured against your own build;
• a requirement describing a feature you scoped out in Week 2 or cut in Week 4, still sitting in the Must column;
• an NFR whose measurement method assumes the brief’s suggested stack rather than the one in ADR-0001.

Produce: a table — inherited sentence, still true?, action taken (edited / cut and logged as CR-nnn / left as-is on purpose). Then make sure docs/scoping-decision.md says in plain words which brief you started from, what you kept, what you changed, and what you cut to fit 160 hours.

Reflect (150 words): How many survivors did you find, and what does that tell you about which weeks you were moving fastest? Adapting well is the accelerated skill. A leftover is not a moral failure — it is evidence about when you stopped reading carefully, which is worth knowing before your first job.

Block B — Prove it (Tuesday–Wednesday)

Rep 5 — 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 reads prose, not execution; 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 6 — 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 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 bite your tongue? 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 7 — Sweep the history before you publish

Three places: files that should never be tracked, the working tree, and every commit on every branch.

cd /tmp/selfaudit
git ls-files | grep -Ei '(^|/)\.env($|\.)|\.pem$|(^|/)id_rsa$|\.keystore$|credentials$'
git grep -nIE '(api[_-]?key|secret|token|password)[[:space:]]*[:=][[:space:]]*[^[:space:]]{8,}'
git rev-list --all | xargs -n 40 git grep -nIE 'AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{20,}'

Read every hit — password = process.env.DB_PASSWORD is exactly correct code and will match, and a scanner you trust blindly is worse than no scanner. 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 output, a line per hit saying real-or-placeholder, and — for anything real — the word ROTATED with a date.

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

Block C — Build the case (Wednesday)

Rep 8 — The run sheet and the one sentence

Fill the run-sheet template in code/talk-kit.md into docs/presentation/run-sheet.md. Ten sections, minutes summing to 30:00 or less, demo ≤ 8:00, questions ≥ 3:00, a key line and a KEEP/CUT marker per section.

Then write the one sentence — 25 words or fewer, no jargon — and test it on a human who has never heard of your project. If they cannot restate what the software does, the sentence is wrong, not the human.

Produce: the committed run sheet, and the one sentence in its final form with the restatement you got back.

Reflect (75 words): Which section did you have to steal minutes from, and what does that say about which part of the project you most want to talk about versus which part carries points?

Rep 9 — The scope slide: adopted, adapted, cut

Three minutes of your talk and twelve points of its rubric live here. Build the slide with three short columns and nothing else:

Started from:  Fast-Start brief #<n> — <its one-line problem>
Kept:          the problem, the user, FR-01..FR-04
Changed:       stack (ADR-0001), 3 acceptance criteria rewritten after Week 2 user interview
Cut:           FR-07 (CR-002, Week 4 — audit projected 190 h against 160)
Shipped:       4 of 4 Musts, 1 of 3 Shoulds

If you brought your own project instead of adopting a brief, the shape is identical: what you committed to in Week 1, what you changed after Week 2, what you cut in Week 4, what shipped.

Produce: the slide, and the ninety-second script you will say over it.

Reflect (100 words): Say the script out loud once. Does it sound like an apology or like a decision? If it sounds like an apology, you have not yet believed the two-thirds rule — 160 hours buys three or four Musts, and scoping to that is the competence being graded.

Rep 10 — Demo script, seeded data, recorded fallback

Fill the demo-script table in code/talk-kit.md into docs/presentation/demo-script.md: exact action, exact expected result, seconds budget, requirement ID, and failure fallback per step. Seed the data with script/seed. Then record the full demo path, trim it to the budget, write the per-step timestamps into the failure column, and play it once with the network disabled.

Produce: the committed script, the recording at docs/presentation/demo-fallback.mp4 (or a link if it is too large), and a note confirming it played offline.

Reflect (100 words): Run the demo cold, on a timer, once. Where did it overrun, and what unscripted click caused it? A demo that breaks and recovers in fifteen seconds costs you almost nothing. One that breaks and gets debugged for four minutes costs you the rest of the talk — and the difference is a decision you make now, in writing, while nothing is on fire.

Block D — Close it (Thursday)

Rep 11 — Change log, tag, release notes, and the access check

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.

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-04): <list>.
      NOT in this release: <FR-07, cut Week 4, CR-002>; <NFR-03 incomplete,
      tracked as DEF-17, 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.

Then 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. Assemble the submission block from code/final-submission-checklist.md and submit it — before the talk, never after.

Produce: the pushed annotated tag, the commit SHA, published release notes in the good shape, confirmation that the logged-out load succeeded, and the submitted block.

Reflect (100 words): Why does naming what is missing earn points on three separate rubric lines rather than costing points on one? Answer in terms of what a grader does with a gap they find themselves. Then, in one sentence about mutability, say why you submit the tag and the SHA rather than a branch name.

Rep 12 — Estimate versus actual, and the retrospective

Open docs/hours-log.csv and do the arithmetic you have been able to do since Week 1 and have probably been avoiding. Then fill code/retrospective-template.md into docs/retrospective.md.

Produce:

• Total planned hours versus total actual, against 160.
• Construction (Weeks 5–6) 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 two sections that carry the document: the decision you would remake (exactly one, cited to an ADR or a change request) and the same 160 hours, spent better (a reallocation table where every row cites something in the repository).

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

GOOD: "Cut FR-11 entirely (7 hours, a Should, neither of my two test users
       asked for it). Six of those hours to NFR-03, which is a Must and is
       still failing as DEF-17. The seventh to Week 3, where I logged 11 hours
       instead of 20 - the thin Week 3 design is why Week 5 went sideways."

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 eight weeks of data and a calendar that punished error twice as fast as a long semester would have.

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 8, writing an evidence note for every line exactly as a grader would. Add one question their repository cannot answer: which parts of this specification still describe the brief rather than the build?

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 delta analysis: every line where you 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 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 8 — Milestone 8, The Final Submission. Fifty percent of the course, and the last thing this book will ask of you.