Definitions

Definitions

The pipeline

Results

1. Generate numbers; do not type them.
2. A rerun changes numbers, so a typed README is stale within a week.
3. Missing sections are easy to detect; overclaiming and weak baselines need a human.
4. Passing my checks does not make a README good.
5. The planted-fault score is circular and only shows that the code matches its author's intent.

Design rules

• Open with one sentence and the user; put the demo and the headline number above the fold.
• Every number has a file and a command behind it; generate tables from results.
• Show the baseline, the interval and n next to every headline number.
• State limits plainly, including what you did not test.
• Keep the quickstart to five commands or fewer and test it on a clean machine.
• Write the architecture note as decisions: chosen, alternatives, evidence, given up.
• Put ten failure examples in the evaluation report, grouped by cause.
• Pin versions and commit the evaluation data (or how to rebuild it).
• Avoid superlatives; let the number speak.
• Re-run and regenerate before every release.

Interview questions, with the follow-ups

Common mistakes

• Typing numbers into the README by hand.
• No baseline, so the number means nothing.
• No interval or sample size.
• Superlatives ("state-of-the-art", "production-ready") without evidence.
• A quickstart that has never been run on a clean machine.
• A demo that shows only the best case.
• Limits hidden or missing.
• A giant README that should be three linked documents.

What the example does not do

• No real project: TicketDraft is fictional and its evaluation is simulated.
• Crude text rules: the linter cannot judge clarity, honesty or whether the baseline is fair; it finds missing pieces.
• Circular validation: the planted-fault test uses faults and rules written by the same author.
• The number check matches claims to values by format and rounding; it misses numbers written as words and can flag harmless numbers.
• No video, diagram or screenshot generation; the demo is a script, not a recording.
• No reviewer data: how people read a portfolio is not measured here.
• Optional real experiment (I did not run this): give your README to three people who have not seen the project, ask each to state what it does, the headline result and one limitation after 60 seconds, and fix what they miss.

For the curious A linter finds missing things, not good ones

My linter checks for missing sections, overclaiming words, a long quickstart, numbers without a baseline or interval, and numbers that match nothing in results.json. It caught 15 of 15 faults I planted, but that is circular because I wrote both the faults and the rules. The example project and its results are synthetic, and no real reviewer was studied.

What you must be able to say (one page)

• A project is judged on its write-up first. The write-up has four parts with four jobs: a README that stands alone, a demo (about 90 seconds), an architecture note (decisions and trade-offs) and an evaluation report (evidence). The structure and the suggested reading depths are my own; I have no data on how reviewers actually read.
• The README answers five questions (my template, in code/mini-portfolio/templates/): what does it do and for whom; does it work (a number with a baseline, an interval and n); what does it cost and how fast is it; what does it not do; and can I run it in a few commands. Eight sections: what and who, demo, results, cost and latency, how it works, quickstart, limitations, licence.
• Numbers must come from a file, not from memory. My example project writes results.json; the README is generated from a template ({{agent.accuracy|pct}}) by a short script. When I re-ran the fictional evaluation with a different seed or size, 5, 3 and 5 of the 9 numbers in the old README were wrong; regenerating from the new results left 0 flags. A README that quotes last week's run is a false statement.
• A linter finds missing things, not good ones. My lint checks for missing sections, overclaiming words ("state-of-the-art", "production-ready"), a long quickstart, numbers without a baseline or an interval, and numbers that match nothing in results.json. On three fictional READMEs: a weak one raised 15 flags, a partial one 4, and the generated one 0. The checker found 15 of 15 faults I planted, but that is circular: I wrote the faults and the rules.
• Report like an evaluator. When reporting on a benchmark, disclose the share of contaminated data and the results on both the full benchmark and the clean subset; the same habit applies to your own evaluation set (how it was built, whether it overlaps what you tuned on). Quality, latency and cost are the columns of your results table.
• Say what the agent cannot do. Users must know what an agent can and cannot do, and when they might need to step in. A useful split is functional transparency for end users (what is happening, why a decision was made, simple controls) from architectural transparency for developers (how agents coordinate, which tools each has, where the capability boundaries are). Capability presets and success-probability indicators can help the first group. Your README and architecture note are the two halves of that for a reader of your repository.
• The architecture note is a list of decisions. For each decision: what you chose, what else you considered, what evidence you had, and what you gave up (module 6 of this level practises this). Add the failure modes, the permissions and approval points, and a cost and latency model.
• The evaluation report is the evidence file. Question, data (how built, size, leakage checks), systems compared with the same tuning budget, metrics, results with intervals, ten failure examples grouped by cause, limits and the exact commands to reproduce. Module 9 of level 13 and level 9 supply the statistics.
• The demo is a script. Ninety seconds: problem (10 s), a live run on a realistic input (40 s), the headline number with baseline and interval (15 s), one honest limitation (10 s), where the code and documents are (15 s).
• Length: the generated example README is 203 words; my checker flags more than 1,200. Put detail in the linked documents.
• What to say in an interview: "My README is generated from the evaluation output, so every number is reproducible with one command; it states the baseline, the interval and the limits; the architecture note lists decisions with alternatives and what I gave up; the evaluation report includes error analysis and how to rerun it."
• Honest limits: the example project and results are synthetic; the linter uses simple text rules; no real reviewer, repository or hiring process was studied.