# A Portfolio Is an Observability Problem I had too many repos and no honest picture of which ones were real. So I built a tool to audit my own mess, and the public page became the last mile of a small operating system. Most side-project portfolios are treated like galleries. You pick the work you're proud of, write a few cards, add links, and hope the story is obvious. That's fine when there are five things. It quietly stops being fine when the work becomes a pile. At some point I looked up and I didn't have a list of projects anymore. I had Python packages, local-first desktop apps, MCP servers, private operator tools, archived experiments, public repos, half-finished systems, stale READMEs, missing licenses, inconsistent topics, and a handful of things that were genuinely good but that I could no longer describe in one sentence. The thing I was missing wasn't a prettier page. It was an honest answer to a simple question: *which of these is actually real?* Which repos are public, which are polished, which have a license, which have quietly rotted, which one am I about to recommend to someone before remembering it has a broken build. I couldn't hold that in my head anymore. And anything you can't hold in your head is an observability problem. So I got curious about whether I could measure it, and then I built the tools to do it. ## GithubRepoAuditor: turning repos into data GithubRepoAuditor started as a way to look at my own GitHub account without relying on vibes. It walks every repo I've started and runs thirteen analyzers across the things that actually decide whether a project is shippable (activity, build-readiness, CI/CD, code quality, community profile, dependencies, docs, discoverability, README quality, security posture, structure, and tests) plus whether the thing looks ready to be shown to another human at all. What mattered wasn't that it *checks* things. It produces **artifacts:** a structured, machine-readable snapshot written to disk, plus a weekly digest. A portfolio shouldn't depend on me remembering which repos are good. It should have a layer that can be inspected, diffed, summarized, and turned into other surfaces. That layer became what I started calling portfolio truth. Not truth in any grand sense, but truth in the operator sense: the current best structured account of what exists. Which repos are public. Which are risky. Which are the strong ones. Which should be fixed, hidden, pinned, archived, or promoted. Once that file exists, the portfolio stops being a hand-maintained brochure and becomes the visible tip of a small system. ## PortfolioCommandCenter: the cockpit Structured data is useful, but a JSON file on disk is not a place you *look*. So the next piece is a desktop app, Tauri 2 and React, that reads the auditor's output and turns it into something operable: a portfolio table, risk tiers, a security burndown, trend charts, a weekly digest, and an automation view. From that automation view it can spawn the auditor, triage the fixes the auditor proposes, dry-run them, and apply the approved ones. The desktop app itself only reads; every write flows through the auditor's own approval rails, never from the app directly. The point isn't to make GitHub prettier. The point is to make the next decision obvious. What needs attention? What got better since last week? What's newly risky? Which repo is dragging the whole thing down? Which one is strong enough to feature, and which one needs a README before it deserves to be seen by anyone? The shape recurs in basically everything I build: - Take a messy operational surface - Extract structured state from it - Make that state visible - Hand yourself a clear next action The domain changes (repos, retrieval quality, notifications, agent memory) and the operating model stays exactly the same. ## The page is the last mile The site you're reading is intentionally simple: a static page, no backend, no build step, no framework. That simplicity is the feature. The complicated part was never the page; it's deciding what deserves to be on it. So the homepage is the last mile of a longer pipeline. The auditor inspects the repos. The command center makes the state visible. A small shared state layer remembers the decisions. And the page presents the final, curated surface: the outcome of the machinery, not the machinery itself. That split is the whole trick. It lets the public artifact stay light and quiet while the private operating layer underneath gets to be as rich and opinionated as I want. A polished surface shouldn't expose every gear. It should show the result of good gears turning out of sight. ## What I actually learned The biggest surprise was how much easier this work got the moment it stopped being purely editorial. Taste still matters. Writing still matters. But the editorial layer gets a lot stronger when it's standing on structured evidence instead of memory and mood. Instead of asking "what do I feel like featuring," I can ask better questions: which projects are actually public and ready, which ones have the strongest proof, which ones are impressive but off to the side, which need a cleanup pass before they earn a card, and the most important one of all: A portfolio is not a bag of projects. It is a map of judgment. It shows what you chose to build, what you chose not to, what you consider finished, how you treat maintenance, and whether you can make systems that stay understandable after the first burst of energy wears off. That last one is the real tell. ## The quiet advantage The sneaky payoff of building your own little portfolio operating system is that it changes your relationship to maintenance. Without a system, maintenance is guilt; you know *something* is probably stale, somewhere, so you avoid looking. With a system, maintenance becomes a queue. Still work, but visible work, prioritized work, work with artifacts attached. That's the operator instinct I trust most, and it generalizes way past a repo list: don't rely on memory when the system can carry the state for you. - If a surface matters, give it a source of truth. - If it can drift, make the drift visible. - If it needs judgment, keep the evidence. - If it repeats, build the tool. That's how a portfolio quietly turns into infrastructure.