All writing

WRITING

Designing for the reader who doesn't trust you

Every claim on this site is falsifiable in one click — why PORTFOLIO.md exists.

July 2026· 2 min read

Every fact on this site traces back to one file: PORTFOLIO.md, sitting in the repo root. Nothing gets written into a component or a page until it's been added there first, with whatever source backs it up. If a claim isn't in that file, it doesn't go on the site. Blank beats a stale or invented claim, every time — no exceptions for how good the missing claim would have sounded.

That sounds like a process detail. It's actually the whole design philosophy, and it came from one realization: the entire value of a portfolio site, as opposed to a resume, is that it's supposedly checkable. A resume says "led a team of five." A portfolio says "here's the repo, here's the commit history, click it." The moment a portfolio contains one claim that doesn't survive a click, it stops being a portfolio and becomes a resume with better typography — worse, actually, because it implied it was checkable and wasn't.

The constraint isn't about honesty in the abstract. It's about what a skeptical reader — the only reader whose opinion actually matters here — does with one falsified claim. They don't discount that one line. They recalibrate their trust in everything else on the page, because you've shown them your verification process has a hole, and they have no way of knowing how big. The asymmetry is brutal: the upside of the inflated claim was small, and the downside is that it's now rational to distrust the true 90% next to it.

This is why three of the system cards on this site don't currently have GitHub links. Those repos are private. I could link them anyway and let visitors 404 — probably nobody would notice for a while. But "probably nobody would notice" is exactly the reasoning that produces a site full of small, accumulating lies, and the entire point of building it this way was to not be that site. A missing link is honest. A dead link is a claim caught.

Verifiability isn't a nice property this site happens to have. It's the architecture — PORTFOLIO.md as the single source of truth, code gated on it being updated first, TODOs left visible rather than silently filled with something plausible. If you're wondering whether that's overkill for a student portfolio: maybe. But the alternative is optimizing for the reader who isn't paying attention, and that reader was never the one who mattered.

Back to all writing