What should the write-up accompanying a portfolio build contain?

Alderway Mobile is a fictional regional telecom carrier. Keepline is the AI copilot Desmond Okafor built as a portfolio project: it drafts a retention offer for a call-center agent the moment a customer's cancellation risk crosses a set line. Corinne Vance is a hiring manager who reads about forty of these write-ups every hiring season.

How to answer this, stage by stage

Nobody is grading whether your write-up looks nice. They're grading whether you know which section actually proves you can think.

Let's learn

A portfolio write-up is the page next to a build that tells a hiring manager which parts were a real decision, and which parts just happened.

Corinne Vance reads about forty of these write-ups every hiring season. Six months ago, most of what she read were two paragraphs: a headline metric and a screenshot. She'd spend maybe ninety seconds on one before moving to the next file.

Lately, more candidates write a full page: a process paragraph, three screenshots, a metric. Corinne now spends six or seven minutes on some of these.

A longer page is not the fix. The write-ups that actually change Corinne's mind are not the longest ones. They're the ones that admit to a real dead end, with something to prove it. Most candidates fill the extra length with more of the happy path instead.

At its worst: a candidate spends a whole evening polishing an intro paragraph and adding a fourth screenshot of the same success, and never once mentions the version he tried and threw away. Corinne finishes the page no more sure of his judgment than when she started.

What I would leave alone: the exact font, color, or layout of the page truly does not matter, and redoing it at the very end costs nothing. Spend none of your one hour there.

The lesson: a write-up is not a diary of everything you did. It is proof of the moments you chose one thing over another. Write the proof first, and let the polish come last, if it comes at all.

Now here is the same thing as a story

The short version above is what you'd say defending your own write-up's structure out loud. Read this one for how Desmond actually rebuilt his.

Desmond Okafor can tell a save-able customer from a lost one before Alderway Mobile's own retention dashboard flags it, four years of doing it by ear on the phones before he ever touched a model.

His first draft of the Keepline write-up went well for a while. He built the copilot on weeknights, wrote up the architecture, and felt good about a clean one-page summary he could hand anyone.

Then the habit thinned in three beats. His first draft had a short paragraph naming one alternative approach he'd considered. His second draft trimmed that paragraph to fit the page on one screen. His third and final draft cut it entirely, since it felt like the least essential part next to a clean screenshot of the copilot working.

A friend reviewing a printed copy circled the tools-and-stack list sitting at the very top of the page and wrote one line in the margin: "This proves you can use tools. It doesn't prove you can think."

The second box is the one most drafts skip. You can't write about a miss you never kept a trace of.

Desmond went back through his old commits hunting for an early, worse version of Keepline, one that had drafted a retention offer using a discount tier that didn't actually exist in Alderway's pricing sheet. He'd almost deleted that screenshot months earlier, since it embarrassed him at the time.

Wording, he could always redo. The decision to keep or delete that one bad screenshot, he only got to make once.

Rebuilding the write-up took about three hours, plus another ninety minutes just hunting through old commits for the screenshot he'd nearly thrown away. The real cost was never the three hours of rewriting. It was that his best piece of evidence, the one that actually proved he'd caught something real, almost didn't survive to make it into the page at all.

Back at his kitchen table on the Sunday night he wrote the first draft, putting the tools-and-stack list at the very top had felt obvious. It was the easiest section to write, and it felt like a natural place to start a technical document. That made complete sense for a page meant to organize his own thinking. It stopped making sense the moment the page's real job changed to persuading someone else he could reason under uncertainty, not just operate a stack.

A clean number alone doesn't say which branch it came from. Only the failure case behind it does.

The next time Corinne opened one of his drafts, she reached the tradeoffs section in under ninety seconds, since it now sat first, and read the whole page in six minutes flat, ending on a real follow-up question about the pricing guardrail instead of a polite pass to the next file.

The old page asked a reviewer to take his judgment on faith. The new page put the proof of it in the very first section she'd read.

I put the tools list first because it was the easiest thing to write, not because it was the thing that mattered. It took one circled sentence in a margin to see I'd built the page for myself, not for the person actually reading it.

ORDER, the write-up broken openNot a checklist of everything a write-up could hold. ORDER is what tells you which one section to write when the clock is the real constraint.

None of these five are about the build itself working. All five are about proving you knew where it didn't.

The tools list and the intro paragraph sit in the same corner: cheap to write, and cheap to fake. The rejected tradeoff sits alone in the corner that actually matters.

The recap, one line per letter: outcome is proving judgment, not just execution. Reversibility is the tradeoffs section being the hardest to backfill honestly. Dependency is keeping the failed screenshot while building, not after. Evidence is one concrete artifact beating a paragraph of assurance. Rank is writing that section first, before anything else, when the hour runs out.

And if you want to be sure it really works, try it somewhere elseSame five letters, a livestock health app instead of a phone call. A field with real animals in it, where a miss costs more than a customer.

Bramwell Agritech is a fictional agricultural co-op. Anwar Deeb built a livestock health-triage assistant there, an AI tool that flags animals worth a vet's attention from daily photos and weight logs. Ffion Pryce reviews his write-up.

Mapped onto ORDER: the outcome the write-up proves is that Anwar understands the real cost of a missed case, not that the model runs on a farm's data. The reversibility test lands on the one section describing an animal the model rated low-risk that later got sick, since a farmer can't un-know that, and a reader can tell a real logged miss from one reconstructed after the fact. The dependency is that Anwar had to actually log that real case, the exact threshold score, the date, the vet's later note, while it was happening, not rebuild it from memory for the write-up. The evidence is one real annotated vet chart showing the miss next to the threshold that let it through, stronger than any paragraph saying the model "isn't perfect." And the rank: write that missed-case section first, since in a field where being wrong costs an animal's health, it's the one section that proves he understands the stakes, not just the code.

Three of these four parts exist because a real animal's case went wrong once. The fourth just says which one gets written down first.

Swap the trigger and it still runs.
Speed: an interviewer caps you at sixty seconds. Say "lead with the section that's hardest to fake: what you got wrong and caught, not what you got right," and stop.
Cost: there's no time to build the write-up twice, only once, in an evening. Even one honest paragraph naming a single dead end beats zero, done in five minutes.
The model gets better, for real: if Keepline's or Anwar's accuracy improves later, that's still no reason to delete the rejected-tradeoffs section. A better model retroactively makes the old failure more interesting, since it shows real movement, not less.

Where people run it wrong.
They write the tools list first because it's the easiest section, the exact mistake Desmond made.
They spend the whole hour polishing wording and never touch the tradeoffs section at all.
They invent a rejected alternative after the fact, and it reads like an afterthought instead of a real decision made in the moment.

How to use it live. When someone asks what a write-up should contain, ask yourself one question first: which section would be hardest to fake if you only had an hour. Write that one first, out loud, before listing anything else.

Flashcards (tap any card to flip it)

Check yourself Score: 0 / 0