The README as a design doc

The reviewer reads your README before the call and plans the call from it, so write it as your voice.

Before you read: predict

A chat take-home goes to an engineer, and the review call is a week away. The candidate's README is one line, npm start. She is saving her design reasons for the call, where she means to present them.

Which statement fits what take-home reviewers publish about how the review runs?

The 30-second version

Reviewers read your code and README before the call, then use the README to guide the call. So write it as your side of that conversation: one command that runs a fresh clone, what you built and skipped, the few decisions that shape the code, the limits and next steps, and any allowed AI use. Keep it short and current.

The reviewer reads your README before the call and plans the call from it, so write it as your voice.

How it works

Step 1 of 13

Read before the call. As of 2026-10-01, Monzo's engineers go through your code before the review call and use your README to guide it. [S1]

Analogy: A dental lab's work ticket, sent back with a finished crown

A technician makes a crown in her lab, and the dentist fits it days later in her own surgery, with the lab's ticket in hand. She reads the ticket before the patient arrives, and the fitting follows it. The ticket says how to seat the crown with what any surgery has, not with the lab's furnace. It says what was made and what was not, the few choices that change the fit (zirconia rather than porcelain: stronger on a back tooth, less lifelike), and the one contact nobody has checked yet. A ticket written before the last adjustment misleads the fitting.

At the dental lab	In the take-home
The dentist reads the ticket before the patient arrives	The reviewer reads the README before the call
Seating it with what any surgery has	One command in a fresh clone
Made and not made	Built and skipped
Zirconia rather than porcelain, and what that costs	A decision with its trade-off
The contact nobody has checked yet	A known limit
A ticket written before the last adjustment	A README older than the last commit

Breaks down when: the dentist can see and touch every surface of the crown, while a reviewer cannot see a reason in code. Wrong inference: “the reviewer will work out why from the code.” The patient also judges only the crown, while a reviewer discusses the README too.

In real terms: before you submit, run the README's command in a fresh clone, then reread every line against the final code.

Examples, run for real

EXH-2310 is a synthetic submission of the ExamHall proctor-dashboard take-home. Its README is one line, npm run dev, copied from an older project's template; the dashboard's package.json defines only start and test. The candidate kept her design reasons for the call. MR !2610 is the resubmission.

EXH-2310 · README run line: npm run dev · fresh clone of the submitted commit
  npm run dev -> exit 1 · npm error Missing script: "dev"
  README headings: (none) · decision entries: 0
MR !2610 · README run line: npm start · fresh clone of the submitted commit
  npm start -> exit 0 · proctor dashboard ready · 3 candidates · filter: flagged -> 1
  README headings: Run, Built and skipped, Decisions, Known limits, Next steps, AI use · decision entries: 2

The resubmitted README, as the reviewer reads it:

Try it

Answer first, then check. Nothing is saved.

Question 1 of 6

Her chat take-home's README says to run it with npm start. Its package.json:

{ "name": "chat-takehome", "version": "1.0.0", "private": true, "type": "module",
scripts": { "build": "node build.mjs", "start": "node dist/server.mjs" } }

npm run build writes dist/server.mjs, and dist/strings.mjs from src/strings.json; src/server.mjs imports ./strings.mjs. The repo has no dependencies. Her .gitignore lists dist/ and node_modules/. She ran the build at 16:00, fixed the unread badge in src/server.mjs at 17:00, committed, and submits at 18:00. The reviewer clones the repo and types npm start, nothing else.

Which change makes that one command run the code she submitted?

Question 2 of 6

She is writing the Decisions part of the README for her 3-hour chat take-home, and has drafted three entries.

Which one belongs there?

Question 3 of 6

Her README for a 3-hour chat take-home has grown to 11 pages: a tutorial on WebSockets, a page for each function, 18 decision entries and a two-year roadmap. The reviewer will read the submission before the call.

What should she do with the README?

Question 4 of 6

Her chat take-home's task sheet asks for sending a message, a conversation's history in the order it was sent, and marking a conversation read. Her submitted chat.mjs:

Her three tests pass: send stores the text, history holds every message and markRead clears the count. Her README's Built and skipped section has three lines.

Which one is false for the commit she submits?

const convs = new Map();const conv = (id) => convs.get(id) ?? convs.set(id, { messages: [], unread: 0 }).get(id);export function send(id, text) { conv(id).messages.unshift(text); conv(id).unread += 1; } // TODO: cap text at 2,000 charactersexport const history = (id) => conv(id).messages;export const unread = (id) => conv(id).unread;export function markRead(id) { conv(id).unread = 0; }export function react() { throw new Error('reactions are not built'); }

Question 5 of 6

On Saturday morning she wrote the README for her chat take-home, including the entry “The message list loads 50 messages a page, with a cursor.” That afternoon she cut file attachments, which were half built, and replaced the paging with one request that loads the whole conversation, to make the deadline. She submits at 18:00; the review call is next Wednesday.

What does the README need before she submits?

Question 6 of 6

Her chat take-home's task sheet says: “Sent messages must survive a page reload.” Her send() answers the browser only after the message is written to a JSON file on disk, and no test reloads the page mid-send yet.

Which line belongs under her README's Next steps?

Go deeper

Pro tip

Before you submit, open your repository's page in a private browser window and read the README there, rendered beside the file list, as the reviewer will first see it.

Checked against the tools and docs as of 2026-10-01.

Predict first