The day I mostly didn't build (and why that was the point)
July 10, 2026Build LogDocumentationResearch
Some days you ship code. Some days you ship clarity. Today produced no features. It produced a project that knows what it is.
Some days you ship code. Some days you ship clarity. Today was the second kind — a long stretch of making the project honest with itself, and pointing the roadmap somewhere real before writing another line.
A tiny UI wart that was actually a mental-model bug
It started with a small complaint: clicking a source in the sidebar "did nothing."
The truth was worse than a bug. It was a hidden dual behavior. A single click quietly set a chat filter, with no visible feedback. Browsing required an undiscoverable double-click. And three different surfaces were all named around the same word.
So I split the control into an explicit browse action and an explicit filter, and renamed the confusing tabs so the in/out split finally reads: one tab is what you put in, the other is what the platform generated.
Small change. Big drop in "wait, what does this do?"
Making the docs stop lying
Then a sharper question: are we even using this framework we keep citing?
I checked the code instead of the manifest. We weren't. Nor three other libraries the architecture doc confidently listed. The code is leaner and more honest than its own spec — hand-rolled retrieval, plain CSS, direct SDKs.
That turned into a ground-truth technology matrix: what we actually use, the alternatives, why, the cost and license, and the boring industry-standard option per slot — each with a "revisit when…" trigger so future-me knows when a choice has expired.
The reassuring finding: we're on the battle-tested option for almost everything, and every deviation is deliberate. The uncomfortable findings: six declared-but-unused dependencies, and one library under a copyleft license that would be a real problem if we ever shipped closed-source. A manifest hides both of those. Only reading the code surfaces them.
The debate that produced it
The good part wasn't the document. It was the argument: frameworks are "free," so why not use them?
Because "free" is the license, not the total cost. Churn, debugging through layers of abstraction, and lock-in creep aren't free. They're just billed later.
The resolution: keep the roll-your-own core, but make components pluggable — so a framework piece can be added where it earns its keep, and never bolted to the spine.
Renaming the cast
A housekeeping pass with teeth: placeholder names across every doc got replaced with real ones.
A blind find-and-replace would have left ragged ASCII diagrams and — my favorite — a slide that listed a product as an alternative to itself. Fixing those by hand was the reminder that "just rename it" is never just a rename.
Pointing the roadmap at something real
The afternoon was pure planning, and I'm glad I resisted the urge to code.
The ask grew, live, from "make the docs accurate" into three linked workstreams. And crucially, I audited the executive deck against reality so nothing it promises falls through the cracks.
That surfaced nine capabilities we'd pitched but tracked nowhere. Live telemetry, impact analysis, missing-test detection, autonomous issue discovery, and more. Sinabi natin sa deck, wala sa backlog (we said it in the deck, it was in no backlog). Now they are.
Ending on research, not code
The UI is a priority pain, so before redesigning I ran a deep research pass on it — 23 sources, 113 claims, 25 of them adversarially verified.
The verdict: move to a named left sidebar (our six top tabs are at the ceiling — several well-known products learned this the hard way), an audience-first dashboard of five to seven cards with conflicts top-left, explicit input-vs-output naming with AI-vs-human provenance badges, and a filtered, aggregated graph instead of dumping the whole database at the user.
It even killed a couple of dashboard myths I'd otherwise have cargo-culted. There is no "maximum five KPI cards" law. Somebody said it once and everyone repeated it.
What I learned
A codebase drifts from its docs the way a person drifts from their New Year's resolutions — quietly, and mostly by not doing the ambitious thing.
The fix isn't to feel bad about it. It's to write down what's actually true, keep the aspiration clearly labeled as aspiration, and make the next step obvious.
Today produced no features. It produced a project that knows what it is. Minsan yun ang kailangan (sometimes that's what's needed).
The audit findings, the research, and the rules that came out
The endpoints, the code, and the specific tooling. Same password as the other Knowledge Platform posts — or request access below.
The UI split, concretely
The source chip had a hidden dual behavior: single-click set a chat filter with no visual feedback; double-click opened the browser. Nobody discovers a double-click. Nobody notices an invisible filter.
Split into a browse action plus an explicit filter funnel with visible state. Gave the tool-server source real styling so it stops looking like a second-class citizen. Renamed the tabs: Explorer (what you put in) and Generated (what the platform made).
The naming was the actual fix. Three surfaces all called some variant of "sources" meant the user had to hold a mental map the UI refused to draw.
The technology matrix
Structure per slot: what we use · the alternatives · why we chose this · cost and license · the most-used/stable industry standard · revisit when…
That last column is the one that matters. A technology decision without an expiry condition becomes dogma. "Revisit when the corpus exceeds N documents" or "revisit when we need multi-tenant" turns a choice into a hypothesis with a falsification criterion.
What the audit found
Six declared-but-unused dependencies. Listed in the manifest, imported nowhere. Every one is attack surface, install time, and a license obligation for nothing.
A PDF library under AGPL. Fine for now. A genuine problem the moment anything ships closed-source. This is the same class of finding as the license audit on my other projects — and it only surfaces if someone actually looks.
The docs listed four things we don't use. A retrieval framework, a CSS framework, a component library, a state library. The code is hand-rolled retrieval, plain CSS, and direct SDKs — leaner than its own specification claimed.
The pluggable-components resolution
The framework debate resolved into a rule rather than a verdict: the core stays hand-rolled and dependency-light; components are pluggable at defined seams.
A framework piece can be added at a seam where it earns its keep. It never becomes the spine. This is the same hexagonal instinct as the device-adapter pattern in my other work — the expensive decision is where the seam goes, and once it's placed, swapping what sits behind it is cheap.
The rename, and why it wasn't a rename
Placeholder vendor names across every document had to become real ones. A blind find-and-replace would have produced:
ASCII architecture diagrams with ragged column alignment, because the new names were different lengths
A comparison slide listing a product as an alternative to itself, because the placeholder it replaced had been the "alternative" column
Both had to be fixed by hand. The lesson generalizes: any transformation that changes token length breaks anything whitespace-aligned, and any transformation that collapses two names into one breaks anything that compared them.
The executive-deck audit
Nine capabilities appeared in the deck and in no backlog: live telemetry integration with query support, impact analysis, missing-test detection, autonomous issue discovery, vendor advisory, document OCR, and three more.
A pitch deck is a promise ledger. Anything in it that isn't in a backlog is a debt nobody has recorded. Auditing the deck against the tracker should be a recurring calendar event, not a thing you notice by accident nine items deep.
The UI research
23 sources, 113 extracted claims, 25 adversarially verified (meaning: actively searched for evidence against the claim before accepting it).
Findings that survived verification:
Six top-level tabs is the ceiling. Move to a named left sidebar. Several widely-used developer tools converged on this independently.
Audience-first dashboard — five to seven cards, conflicts in the top-left where the eye lands first.
Explicit input-vs-output naming, with provenance badges distinguishing AI-generated from human-authored.
Filter and aggregate the graph. Dumping every node at the user is a demo, not a tool.
Findings that didn't survive: the "maximum five KPI cards" rule has no evidence behind it. It's a repeated assertion, not a research finding. I'd have cargo-culted it.
Next
Turn the UI research into a concrete dashboard and information-architecture redesign — four decisions to make first. Then the documentation reconciliation. Then the feature that generates technical documentation from the codebase: diagrams, traces, flows, updating on new commits and flagging bugs and refactor candidates.
Build log entry from a daily journal. Written the evening of the work, lightly edited.