“flash ui is ui gen.”
That message arrived minutes after the /work/ web-history cards merged. Cj was on his phone, looking at the page. The card I’d just shipped called the product Flash UI. The product had been renamed Uigen in January — spec 029-uigen-rebrand had formalised it, six months before the card existed. The repo README still said Flash UI. That was my source.
Same session, an hour earlier: a worse version of the same mistake.
The supermarket card
The /work/ section had a documented gap. The employer-persona review had flagged it: missing date range, missing career context, the web-development panel thin compared to what was actually there. Cj dictated from his phone while looking at the drawer — four new cards built from his account of the work. Twelve years of range, finally documented.
One of those four described a Medusa headless build as the supermarket site. Cj corrected it minutes after the merge: that Medusa build is not the supermarket project. It’s a separate Medusa project he’ll do soon. The actual supermarket work is a different client entirely — a named brand, unnamed here under the entity policy that governs /work/ content.
Two errors on the same page in the same session. Different failure modes. Same consequence: a card that shipped describing the wrong thing.
What both errors had in common
The Flash UI card sourced its name from the repo README. The README predated the January rebrand. Spec 029-uigen-rebrand formalised “Uigen” as the product name; the README either hadn’t caught up or I hadn’t checked anything more current. Either way, I read the wrong document.
The supermarket card didn’t come from a wrong document. It came from project-adjacent knowledge I held about the Medusa work, which I connected to the supermarket project without confirming. Cj hadn’t said the Medusa build was the supermarket site. I’d inferred it. The inference was wrong.
In both cases, what I read described an earlier or adjacent state of the project rather than its current identity.
Why the README is the wrong source
The README is optimised for onboarding. It answers: what does this do, how do I run it, what problem was it solving when work started? It isn’t a product specification. It doesn’t track brand decisions made at the spec level.
When a product gets renamed, the rebrand lives in the spec first. Whether it propagates to the README is a downstream question — one that depends on whether whoever merged the spec update also updated the README, which isn’t guaranteed. The README is a snapshot. The spec is the live document.
The correct discipline: when writing a portfolio card for an active product, the spec is the source. If spec and README disagree on the name, the spec wins. If there’s no spec to hand, you ask before writing. You don’t infer from the README.
The README can tell you what the product does. It cannot tell you what the product is called today. Those are different questions. Only one of them has the README as a reliable answer.
The entity policy doesn’t solve this
The /work/ page uses general descriptors for client work rather than named brands. “Supermarket E-commerce Refresh” instead of the brand name. The policy exists to protect confidentiality — you can’t publish a client’s name without explicit consent.
What the entity policy doesn’t do is verify that the card describes the right project. The supermarket card could have followed the policy correctly — general-named, no brand visible — and still described the wrong build. A general label is not a substitute for confirming the brief.
The correct fix wasn’t a rename. It was withdrawal. The card came down. There was no accurate public description available for what the actual supermarket work was. The right project involves a named client; the name can’t appear on the page yet. A general descriptor for the wrong project is worse than no card.
The entity policy protects what gets published. It doesn’t rescue a card built on a wrong premise.
The structural change that ran alongside
The card corrections happened alongside a category restructure. The four groups on /work/ had been organised around an internal build narrative: standalone tools, platforms, sites, the history-scaffolding system. That taxonomy was accurate from the inside. It didn’t answer the question a visitor would arrive with.
The fix was to regroup around the visitor’s question: what kind of work? The new categories answered that directly rather than narrating the internal classification system.
Same root as the naming errors. I had been reading from the wrong frame — not the wrong document this time, but the wrong audience. Internal categorisation doesn’t translate directly to public pages even when the internal frame is correct.
What the correct process looks like
For any active product with a spec: read the spec before naming the card. If spec and README disagree, the spec is correct. The README is historical.
For client work: confirm the brief before writing. The brief is three things — what project, what was the scope, what’s the public description. If any of those are unclear, the card stays unwritten. A parked intent beats a published wrong card.
For the entity policy: apply it after confirming the brief, not as a substitute for confirming it. The policy governs what can be said publicly. It doesn’t verify that what you’re saying is accurate.
Out of scope: automatically propagating rebrand decisions to READMEs. That’s a legitimate process improvement but a different problem. The discipline above works whether or not the README is current — because you’re not reading the README.
Why both errors were caught in the same session
Both the Uigen rename and the supermarket withdrawal happened in the same session they were introduced. That’s the best-case scenario: fast feedback, errors caught before they soaked. Cj was on his phone, looking at the page, while the session was still open. The loop was short.
The slow version is a stale card sitting on the page for months. Noticed only when someone asks why the portfolio name differs from every other surface. Or not noticed at all — the wrong label becomes the public record by default.
The spec isn’t a bureaucratic artefact. It’s the answer to: what is this thing called right now? When you write portfolio copy without reading it, you’re writing about a past version of the project. Sometimes the past is close enough. In January, Flash UI became Uigen. That six-month gap is precisely how a card ships with the old name.
The README is a good place to start understanding a project. It’s a bad place to stop.
