You send the repository link — on a resume, in an application form, in a
referral message — and nothing comes back. No interview, no feedback, no
question. On the reviewer's side the session looked like this: clone, pip install -r requirements.txt, run the entry script, and one of these appears
within two minutes.
FileNotFoundError: '/Users/<author>/Desktop/data/customers.csv'
ModuleNotFoundError: No module named 'sklearn'
KeyError: 'OPENAI_API_KEY'
TypeError: ... (a library version changed under an unpinned requirement)
README says "run the notebook" — there are 4 notebooks, unnumbered
Then the tab closes. The candidate never learns that the project was opened at all, and often believes the link was ignored.
Any application where a repo link is the evidence: fresher applications, take-home submissions, referral messages, and portfolio-inbound screening at startups and GCCs. It happens to good projects. The code usually works — on the machine where it was written, inside an environment that grew over weeks, with a data file sitting in a folder that only exists there. The author has never started from zero, so every assumption is invisible to them and fatal to everybody else. Take-home rounds are the harshest version, because a reviewer with twenty submissions gives each one a fixed budget of about five minutes. Linked modules: 4.1 (Notebook to repo), 6.8 (Resume, GitHub, LinkedIn, portfolio).
The reviewer is not evaluating your code. He is testing one claim: that the thing you described exists and produces the number you quoted. That test is a clone into a fresh folder, and it fails for a short, repeatable list of reasons.
Cause 1 — a path that only exists on your laptop. An absolute path, a Desktop folder, a Windows drive letter. It fails on the first line that reads data.
Cause 2 — data with no instructions. The gitignore correctly kept the csv out of the repo, and nothing in the README says where the data comes from or how to rebuild it. This is the invisible one, because the file is present on the author's disk and absent everywhere else.
Cause 3 — unpinned versions. pandas instead of pandas==2.2.3 means the
reviewer installs whatever shipped this month. Either it breaks, or worse, it
runs and prints a different number than your README claims.
Cause 4 — secrets assumed. The code reads an API key from the environment and
the README never mentions it, so the run dies on a KeyError that looks like the
project needs a paid account to evaluate.
Cause 5 — no single entry point. Four notebooks in unclear order, or a README whose first instruction is "open the notebook and run the cells". A reviewer will not choose for you.
The cost is asymmetric and silent. A repo that fails to run does not score zero; it scores below zero, because the resume line that pointed at it is now a claim the reviewer watched fail. And no feedback arrives, so the same broken link goes out with the next thirty applications.
Run the ritual from module 4.1 against yourself, and fix what it prints.
The clone test, exactly as a stranger runs it:
cd /tmp
git clone <your repo url> fresh-check # different folder name, on purpose
cd fresh-check
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python train.py # the ONE command your README names
Your own shell must not be used to help. No editing, no "oh, you also need to…". Whatever fails here is a defect, and each has a small fix:
DATA = Path(__file__).parent / "data" / "customers.csv".requirements.txt beats a forty-line
pip freeze dump..env.example, name the variables in the README, and make
the project runnable without any paid key if you can, even in a reduced mode.Then make the README carry the result. Problem in two lines, a small results table with the baseline row first, the run block above, a "what this does not do" section, and a one-line file map. A reviewer who sees his terminal print the same numbers as your table has verified your resume without asking you anything.
Finally, test it on a human. Hand the link to a classmate who has never seen it, start a stopwatch, and say nothing. Every question they ask is a README edit, not an explanation.
Treat "a stranger runs it in five minutes from the README alone" as the definition of done for any repo you will ever link, and re-run the clone test before every submission, not once a semester. Keep data out of git and keep a regeneration path in code, so a clone is always self-sufficient. Pin versions on the day you write the requirements file, because the day you need them pinned you will not be watching. Commit in small steps as you work: a history of many small commits is also evidence of authorship, while a single "final project" commit raises the question this entry's neighbour WR-169 is about. Add a dated line to the README saying when the run block was last tested on a clean machine, and re-test whenever that date is older than your last dependency change.
Q: "I cloned your project last night and it failed on the first run. What happened?" Strong answer: do not flinch, and do not guess. Ask which command and which error, name the likely cause in one sentence ("if it stopped at the data load, that is on me — the csv is gitignored and the regeneration path was added after you cloned"), say what the fix is and where it lives, and then offer the verification: "the README's run block is tested on a fresh clone, and the expected last line is accuracy 0.824, recall 0.667, 26 of 39." A candidate who owns a broken clone and can name the file that breaks is still credible. A candidate who says "it works on my machine" has confirmed the diagnosis in this entry.