January 25–27
“Go deep and thorough on modeling FIRST, to prevent future flattening. Only THEN discuss MVP scope. Document the cathedral, then decide which rooms to build first.”
That was the guidance I gave on January 25th. Three days later, we released v0.8.5 and unblocked three alpha testers who had been waiting for more than a week to log in.
The philosophy
We were about to implement MUX-IMPLEMENT, the implementation sprint of our Modeled User Experience super epic. This one brings to life the updated navigation, documentation access, lifecycle indicators, and addresses core accessibility requirements.
The temptation was to dive straight into code, but I’ve been burned by this attitude before. Features implemented without thorough modeling tend to flatten over time. Edge cases get papered over. The underlying concepts drift, especially if they had acquired a special meaning in the course of discussion, unavailable without the full original context. Six months later, you’re maintaining code that no longer reflects what you actually believe about the domain.
So I asked the Lead Developer to start with a deep investigation instead. Not just “what do we need to build?” but “what does our object model actually say, and how does this feature express it?”
This caution didn’t come from nowhere and it didn’t just come from conventional wisdom or existing investigation patterns. I still remember how our intial implementation of my innovative (if I do say so myself) spatial integration model ended up “flattening” some of the key concepts and led to a full refactor to, well, reinflate things.
The base camps
The investigation took a full morning. The Lead Developer visited ten “base camps” — documents that contained pieces of our MUX philosophy:
ADR-045 for the Five Pillars of Consciousness. The UX Foundations document for the “Radar O’Reilly” pattern (Piper isn’t a destination, they’re a companion). The anti-flattening guide for the difference between “Piper noticed” and “Query returned.” The ownership metaphors for the Native/Federated/Synthetic distinction.
By the end, something had shifted. The navigation work wasn’t just “add some menus.” It was “express Piper’s current awareness through lenses, gated by trust.”
The synthesis
We had a design discussion that covered five key questions.
What should the home state be? A “workspace” showing harder and softer objects, adaptive to what the user is working on, gated by trust level.
How do lenses manifest? As tokenized natural language — “stuck” and “urgent” as tappable concepts, named but conversational.
Is the standup a paradigm? Yes — a one-shot entry point that flows into conversation, following the pattern of chat to artifact to hardening.
Are places portals? “Brilliant,” said the Lead Developer when I suggested it, the sycophant! (just kidding, fella). “Windows, not links.” Each place type has its own atmosphere.
What about existing navigation? It becomes a utility layer with a command palette for power users who know what they want.
[PM PLACEHOLDER: Which of these five felt most important or surprising?]
The sprint
With the cathedral documented, we could decide which rooms to build.
P1 took one afternoon: home state, utility navigation, command palette, and place windows. 185 tests.
P2 took one evening: document access, lifecycle indicators, composting views. 302 tests.
P3 took another evening: conversation memory, channel consistency, follow-up detection. 407 tests.
P4 took the final push: WCAG 2.1 AA accessibility compliance, design token enforcement, contrast testing. 638 template validations.
All told: 10 days from starting the MUX track to releasing v0.8.5. Over 1,000 tests added. Every P1-P4 issue closed.
The release
v0.8.5 went out on January 27th. The release notes listed lifecycle indicators on todos, projects, and work items. New views for work items and project details. Full accessibility compliance. Design token system enforced across 27 templates.
But those features weren’t the point. The point was that three alpha testers had been waiting on bug fixes that blocked their onboarding. Those fixes were included too, and now they could proceed.
The pattern
I alluded to our Cathedral Doctrine we’ve baked into our agent prompts and briefings”: document the full vision before deciding what to build now, provide the right amount of context for each level to help it make sense in the larger scheme of things without overwhelming or distracting.
It’s slower at the start. That morning of base camp visits didn’t produce any code. The design discussion didn’t ship anything.
But it meant the code we did write was grounded. Every feature traced back to a principle. Every UI decision connected to a concept. When questions came up during implementation, we had answers that weren’t ad-hoc.
The alternative — start building and figure out the philosophy along the way — feels faster but isn’t. You build, then discover an inconsistency, then patch it, then discover another inconsistency somewhere else. The flattening accumulates until the codebase and the concepts no longer match.
The meta-lesson
There’s a reason cathedrals have blueprints.
Not because the architects don’t trust the builders. Not because spontaneity is bad. But because a cathedral is too complex to hold in your head, and too expensive to rebuild if you get it wrong.
The MUX object model is our blueprint. It says entities experience moments in places. It says awareness, not data. It says atmosphere, not contents.
When we document the cathedral first, we’re not slowing ourselves down. We’re making sure the rooms we build fit the structure we’re building inside.