Chapter 1 — Reps

Twelve reps in three blocks: Stand up the shop, Decide, Prove it. They are not warm-ups beside the milestone — they are the milestone, built one piece at a time. Finish the last one and docs/charter.md and docs/scoping-decision.md are mostly written.

Ground rules

• Friday is real. Reps 1–4 are Monday and Tuesday. Reps 5–7 are Tuesday and Wednesday. Reps 8–12 are Thursday and Friday. In an eight-week course the schedule is not a suggestion; it is the deliverable.
• Everything lands in the repository. If a rep produces an artifact and the artifact is not committed, the rep is not done. Your grader reads Git, not your intentions.
• A number, a date, or a quote — every time. A rep is finished when it has produced something checkable by someone who is not you.
• You are adapting, not authoring. From Rep 5 on, every rep is about your chosen brief. No toy examples, no hypotheticals.
• Log as you go. Each rep is at least one row in docs/hours-log.csv, written before you close the laptop — estimate first, then work, then record the actual.
• Write the reflections in prose. Two to four sentences. That is where the thinking actually happens, and the milestone will ask you to pull from them.

Block 1 — Stand up the shop (Monday–Tuesday)

Rep 1 — Create the repository and scaffold it in one commit

Build the canonical tree from §1.6 in a single initial commit, with placeholder files so Git actually tracks the paths. Do this before you have chosen a project — none of it depends on the choice.

git init capstone && cd capstone
mkdir -p docs/adr docs/change-requests docs/evidence docs/interviews \
         src tests script tools .github/workflows
for f in charter scoping-decision ai-usage requirements definition-of-done \
         architecture plan risk-register design-review test-plan test-results \
         defect-log runbook clean-machine-test handoff retrospective; do
  printf '# %s\n\nPlaceholder. See the course schedule for the week this is written.\n' "$f" > "docs/$f.md"
done
printf 'date,start,end,hours,phase,hat,task,estimate_hours,blocked_hours,notes\n' > docs/hours-log.csv
printf 'requirement_id,source,design,code,test,status\n' > docs/traceability.csv

# Three root files, seeded rather than left empty.
printf '# Changelog\n\nKeep a Changelog format, newest first.\n\n## [Unreleased]\n### Added\n- Repository scaffold and document slots.\n' > CHANGELOG.md
printf '.env\n' > .gitignore
printf 'License decision deferred to Week 3 on %s. Reason: <one line>.\n' "$(date +%F)" > LICENSE

# Git does not track empty directories. Every one of them needs a .gitkeep.
touch docs/adr/.gitkeep docs/change-requests/.gitkeep docs/evidence/.gitkeep \
      docs/interviews/.gitkeep src/.gitkeep tests/.gitkeep \
      script/.gitkeep .github/workflows/.gitkeep
git add -A && git commit -m "chore: scaffold capstone repository structure"

This is the same tree Appendix A §A.4 builds — same names, same .gitkeep files — so the two never disagree about a path. Three details are worth reading twice. script/ and .github/workflows/ get a .gitkeep like everything else, because a directory Git is not tracking does not survive a clone, and the Week-7 clean-machine test is exactly a clone. CHANGELOG.md opens with the Keep a Changelog header (https://keepachangelog.com/) that Weeks 6 and 7 fill; .gitignore has .env in it on day one, before there is anything worth ignoring; and LICENSE carries a dated deferral line you still have to finish — a dated deferral is a decision, an empty file is a hole. The one canonical path this commit does not create is README.md, which is Rep 2. After Rep 2, the structure audit in Rep 4 reports all twenty-eight paths present, from a fresh clone, and anything it lists as missing after that is yours.

Produce: the commit, and the output of git log --stat -1.

Reflect: Eleven of those files will not be written for a month or more. In two sentences, and in terms of what a reader of your repository sees, say why creating the empty slot now beats creating the file in the week you need it.

Rep 2 — Write a README.md a stranger can use on day one

Five things and nothing else: what this repository is, who owns it, what state it is in right now, how to navigate docs/, and where the hours log lives. It gets rewritten in Week 7. It must be honest today.

Bad

# Capstone Project
My senior capstone. Coming soon!

Good

# <working title> — accelerated capstone

By <name>, <term>. **Status: Week 1 — engineering system and scope only.
No application code yet.** Adapted from Fast-Start brief #<n>.

## What is here
- `docs/charter.md` — purpose, capacity, non-goals, risks, working agreement
- `docs/scoping-decision.md` — the brief I adopted, what I changed, and what I will not build
- `docs/hours-log.csv` — every work session, logged the day it happens
- `docs/ai-usage.md` — which AI tools are used on this project, and how
- `src/`, `tests/`, `script/` — empty until Week 3

## How to run it
Nothing to run yet. From Week 3 this section is the clean-machine setup path.

Produce: README.md, committed.

Reflect: The bad README is barely shorter. Name the specific question each of the good one’s five parts answers, and say which one a grader checks first.

Rep 3 — Build the board, with a limit on it

Five columns — Backlog · This Week · In Progress · Blocked · Done — and a work-in-progress limit of two. If your tool cannot enforce the limit, put it in the column description and enforce it yourself. Then create six cards for this week’s work, each with an estimate, a hat, and a stopping condition. Rewrite these three before you add your own:

Produce: a screenshot or export of the board with six well-formed cards.

Reflect: Which card was hardest to give a stopping condition to? That difficulty is information — what is actually unclear about that piece of work?

Rep 4 — Wire the hours log and block all eight weeks

Copy code/week1_check.py into tools/ and run it against the log you created in Rep 1:

python3 tools/week1_check.py --root . --log docs/hours-log.csv

It will tell you which canonical paths are missing and print your hours against the 160-hour budget. Then open the calendar you actually use and block your working sessions for all eight weeks — blocks of two to three hours, not scattered singles. Find the week that is already broken (another course’s exam, a holiday, a shift you cannot move) and push those hours forward into an earlier week. Not backward. Backward is how the late start happens, and in eight weeks you get to do this exactly once.

Produce: the committed log with at least one real row, the check output, a calendar screenshot, and a line in docs/charter.md §3 naming the broken week and where its hours went.

Reflect: How many of the 160 hours did you actually manage to place? If it is fewer than 140, you have just discovered the most important fact about your term — in Week 1 rather than Week 6. What has to change?

Block 2 — Decide (Tuesday–Wednesday)

Rep 5 — Shortlist three briefs and run the Decision Engine on all three

Read Appendix B with a timer on: ninety minutes, no more. Shortlist three briefs you would genuinely accept — no decoys; a grader can spot a decoy in about ninety seconds, because nobody screens an idea they have already discarded. Then run The Week-One Decision Engine on the chapter page for each one, unmodified, before you have a favorite.

Produce: the completed table, committed as part of your scoping notes.

Reflect: Which lever moved the number most — feature count, integrations, authentication, or novelty load? Most students expect feature count and are wrong.

Rep 6 — Kill two, in writing

Two rejection paragraphs, written while you still like the ideas. Each names the specific gate that failed, the number or the quote that killed it, and either the condition under which you would revisit it or the plain words closed, not deferred. A model of the form:

Rejected — brief #, . Failed the Build gate. It needs two technologies I have never used plus a message queue, which puts my novelty load at three against a limit of two; the Decision Engine put it at 96 hours after both of its suggested cuts, against a 30-hour feature budget. Revisit only if I can swap for . Otherwise closed.

Produce: two rejection paragraphs in docs/scoping-decision.md §9.

Reflect: Read both aloud. Does either sound like it was written to justify a decision you had already made? If so, rewrite it around the evidence rather than around the conclusion.

Rep 7 — Thirty minutes with one human being

A brief names a user role. It does not excuse you from finding a person. Thirty minutes is enough: five questions, all past tense, no pitch, and no description of your project until the very end.

1. Walk me through the last time <the problem> happened. What did you do?
2. What do you do about it today?
3. What is the most annoying part of how you handle it now?
4. Have you paid for or installed anything to deal with it?
5. When was the last time? And before that?

Write it up the same day: date, length, who they are, the workaround they already use, and three verbatim quotes. If your project genuinely has no user but you — a developer tool, a simulator, a replication — say so plainly in one sentence and substitute a competitive scan of three existing tools. Do not invent a user; a grader can tell, and so can everybody else.

Produce: the write-up, committed, and three quotes carried into docs/scoping-decision.md §3.

Reflect: What did they say that the brief did not predict? That sentence is your first adaptation, and it belongs in Rep 8’s table.

Block 3 — Prove it (Thursday–Friday)

Rep 8 — The adaptation diff

The signature rep of this edition. List everything you are changing about the brief — the user, the domain, a dropped feature, a swapped integration, a narrowed scope — and for each one, name the drafted requirements it touches.

Then do the inverse pass, which is the one people skip: read every drafted requirement in the brief and mark it carry / repair / withdraw. A requirement you carried without reading is a requirement that describes somebody else’s project.

If your honest answer is “I changed nothing,” write that sentence and sign it. Adopting a brief as-written is a legitimate path — pretending you adapted one is not.

Produce: the adaptation table and the marked requirement list in docs/scoping-decision.md §4.

Reflect: Which requirement was hardest to classify? Nearly always it is one that is half true of your project. In one sentence, say what makes half-true requirements more dangerous than false ones.

Rep 9 — Cut to the Must list, bottom-up

Estimate by hand, in vertical slices. For every candidate Must feature list the tasks and put hours on each: interface, handler, data access, validation, error path, test, documentation line.

Feature 1: ______________________
  interface ___ h   handler ___ h   data ___ h   validation ___ h
  error path ___ h  test ___ h      docs ___ h        subtotal ___ h
Feature 2: ...
                        FEATURE TOTAL ___ h   (plan 30, ceiling 40)

Then cut until you have three or four Musts and the total fits. Put the reconciliation next to it: your bottom-up number, the Decision Engine’s number from Rep 5, the gap as a percentage, and the assumption that differs. Do not average them — averaging hides the thing you needed to learn.

Produce: the estimate and the reconciliation in docs/scoping-decision.md §5, and one board card per Must feature.

Reflect: Which feature surprised you by being expensive, and which task did you almost forget to include? Would you have remembered it in Week 5, or discovered it?

Rep 10 — Eight things you will not build, and the one hard part

Write at least eight out-of-scope items, by name. Specific: “email notifications,” not “extra features.” At least two must be things you genuinely want to build — that is how a reader can tell the list is honest rather than composed of things nobody would have built anyway.

Out of scope — will not be built:
1. ______________  5. ______________
2. ______________  6. ______________
3. ______________  7. ______________
4. ______________  8. ______________

Then name exactly one hard part, in two sentences. If you can name three, you have three projects. If you cannot name one, you have a term of typing.

Produce: §7 and §12 of docs/scoping-decision.md.

Reflect: Which of the eight will be hardest to keep out at 11 p.m. in Week 5? Write one sentence to your future self explaining why it stays out. That sentence is the whole point of this rep.

Rep 11 — Prove every dependency, count your novelty load

A brief’s suggested stack is a suggestion, verified for nobody. For every external thing your project needs — an API, a dataset, a device, an account, a permission — make one real call or one real download, this week, and save the output.

curl -s -o /dev/null -w "%{http_code}\n" "https://<the-endpoint-you-plan-to-use>"

Anything you could not exercise is marked UNVERIFIED — an unverified dependency is not a dependency, it is a wish with a URL. Then list every technology the project needs and mark each known (you have shipped something with it) or new (you have read about it). Novelty load above two is a warning; write the sentence “To keep this I would swap ___ for ___, which I already know.”

Produce: the table and the novelty count in docs/scoping-decision.md §10, with saved evidence and dates.

Reflect: Be honest about one item you marked “known.” Have you shipped with it, or followed a tutorial? The gap between those two is where estimates go to die.

Rep 12 — Set your AI policy, then pressure-test the brief

Copy code/ai-usage-template.md into docs/ai-usage.md and fill the policy header completely: which tools, which model versions as best you can name them, what each is for, and what it is never for.

Then run one deliberate Amber-zone use — the one that earns its keep this week:

"Here is a project brief: <paste it>. My situation: I know <X and Y>, I have
 never used <Z>, I have about 30 hours of net feature construction across
 8 weeks, and I work alone. List the ten tasks in this brief I am most likely
 not to have counted. For each, give an hour estimate and one sentence on why
 students underestimate it. Do not be encouraging."

Keep some of what comes back. Reject some. Verify at least one factual claim it makes — a rate limit, a license, a library name — against the vendor’s own page, and record the date. Then write the log entry with all six columns filled.

Produce: docs/ai-usage.md with a complete policy header and at least two entries.

Reflect: The “What I changed” column carries the grade. Read yours. If it says “nothing,” you did not verify — go back and find the thing that is wrong, because there is always something.

Done? One Last Thing.

Assemble both documents, then prove they exist somewhere other than your laptop.

1. Copy code/charter-template.md into docs/charter.md and fill every section — including §2, which in this edition is filled this week, not next.
2. Copy code/scoping-decision-memo.md into docs/scoping-decision.md and fill it from the reps: the decision (Rep 5), the rejections (Rep 6), the evidence (Rep 7), the adaptation record (Rep 8), the Must list and reconciliation (Rep 9), out-of-scope and the hard part (Rep 10), the feasibility screen (Rep 11).
3. Write the scope-cut trigger with a checkable condition and a real date — the Week-4 review is the natural one. Decide it now, while you are calm.
4. Push everything, then clone the repository fresh into a directory you have never worked in, or into a cloud environment (Appendix A):

   git clone <your-repo-url> /tmp/capstone-check && cd /tmp/capstone-check
   python3 tools/week1_check.py --root . --log docs/hours-log.csv

   Read your own README.md as if you had never seen the project. Fix the README, not your memory.
5. Delete /tmp/capstone-check. It served its purpose.
6. Commit: M1: charter, scoping decision, engineering system.

Then hand docs/scoping-decision.md to a classmate. If they can tell you what you are building, what you are not building, what you changed about the brief, and what would make you cut scope — without asking you a single question — you are ready for Week 2.

Up next: Milestone 1