yaodong.dev

The Bottleneck Is the Process

Sun, 29 Mar 2026 14:40:29 GMT

The paradox

AI made every node in the software pipeline faster. But the pipeline itself did not speed up.

In a controlled experiment by GitHub, developers using Copilot completed a coding task 55 percent faster than those without it.¹ At the organizational level, Faros AI’s study of over 10,000 developers found that teams with high AI adoption completed 21 percent more tasks and merged 98 percent more pull requests, but code review times increased by 91 percent.² And in a randomized controlled trial by METR, sixteen experienced open-source developers completed 246 tasks with AI tools and were 19 percent slower. Before the experiment, they predicted AI would speed them up by 24 percent. Afterward, they still believed it had.³

Something is absorbing the gains. The bottleneck is the process itself: the handoffs, reviews, build cycles, and approval gates that sit between the nodes. But you cannot simply remove them, because they carry real weight. The work is to understand what they carry and where it went.

Why the harness exists

Every software engineer knows the rhythm. A product manager arrives with wireframes. Engineers ask clarifying questions, push back. The wireframes are revised. A technical design document is drafted, debated, finalized. Only then does anyone write code. And once the code is written, it enters a review queue, passes through QA, and, weeks after the original idea, reaches production.

This process evolved over decades, shaped by a basic reality: building software is expensive, and the people building it can only hold so much in their heads at once. The product manager understands users but not system architecture. The engineer understands architecture but not market context. The process connecting them bridges these gaps.

This is not so different from what AI engineers now call a harness: the scaffolding you place around an imperfectly reliable executor. Guardrails, validation layers, checkpoints. You build it not because the executor is useless, but because it is powerful and fallible at the same time.

Each node in the traditional pipeline is a control point where someone checks that the work so far is sound before it moves forward. Some bridge cognitive gaps: a design review validates feasibility, a code review catches logical errors. Others exist for institutional reasons: compliance, accountability, alignment. AI will reshape each of these differently, because they exist for different reasons.

The nodes got faster, the seams did not

AI changed what a single person can do. A product manager with access to AI can generate a working prototype rather than drawing static wireframes. An engineer can explore user research, analyze feedback data, produce documentation, all without waiting for a specialist. The boundaries between roles have started to blur.

But the friction is not in the nodes. I run multiple AI agents in parallel using tmux and a set of custom tools. Code generation has scaled dramatically. But my team’s process has not changed: the code still goes through Jenkins, the build is slow, and it often fails. Fixing a failing test means editing, committing, rebuilding, and waiting again. If another test breaks, the loop repeats. Code review is still manual. QA is still manual. The bottleneck is not just that I can produce code faster than the pipeline can absorb it. It is that the pipeline contains cycles, and each cycle runs at the old speed.

The process was built for a different tempo. AI changed the nodes but left the interfaces intact.

What happens when you try to remove them

The natural response is to strip away the process. If the connections between steps are the bottleneck, get rid of them. Less oversight, fewer checkpoints, a leaner pipeline.

The instinct is understandable, but it misreads where the weight lives.

The output is less reliable than it looks

CodeRabbit’s analysis of 470 open-source pull requests found that AI-generated code introduces 1.7 times more issues than human-written code, with security vulnerabilities increasing by roughly 2.7 times.⁴ Most AI-generated code I see has issues of some kind. And as models get smarter, the issues get subtler, harder to catch in review, more likely to reach production unnoticed. Shipping AI-generated code without rigorous validation is not a streamlined workflow. It is negligence with extra steps.

The work found new owners

On a side project where I had no designer, I used AI to generate UI components. It worked, until I needed consistency across the product. The AI produced screens that each looked good on their own but belonged to different applications. So I built a design system: color tokens, typography scales, spacing rules, reusable components, all documented thoroughly enough that the AI could follow them. This was not a shortcut around design discipline. It was design discipline, carried by someone who was never a designer.

This pattern runs in every direction. A product manager with AI can generate a prototype and discuss it directly with customers, skipping the cycle of handing requirements to a designer, waiting for mockups, and cycling back through feedback. Designers are crossing into engineering: Jenny Wen, who leads design for Claude at Anthropic, describes spending a growing share of her time writing code, polishing implementations, and pairing directly with engineers, work that used to sit entirely on the engineering side.⁵ The roles blur, but the discipline of each role follows whoever picks up the work.

AI does not just blur roles. It moves the cognitive work of each role to whoever picks up the new capability. The harness did not get lighter. It found new owners.

The work moved inward

The migration runs deeper than role boundaries. Even within a single role, the cognitive work that the process used to carry did not vanish. It moved inward.

In the traditional model, the harness lived between people: the handoff from PM to engineering, the pull request review, the QA gate. Quality was a collective responsibility, distributed across roles and enforced through process.

In the AI-augmented model, much of that work moves inside the individual. The PM who once needed an engineer to assess feasibility now generates a prototype directly, but must judge its soundness alone. The engineer who once relied on a QA team now works with an AI that writes tests, but must decide whether those tests are meaningful.

This is what the METR results show. Those experienced developers were not failing to use AI. They were doing what the new model demands: spending more time evaluating, testing, and reworking AI output than they saved by generating it. They were building the harness inside their own heads.

If this pattern holds, the implication is clear: junior and mid-level engineers use AI to produce more output, and the verification cost flows upward to the senior engineers who can judge whether that output is sound. The harness does not distribute evenly. It concentrates on the people who can bear it.

The trail went cold

There is a subtler loss. Traditional workflows produced institutional knowledge as a byproduct. Design documents recorded not just what was built, but why. Pull request discussions preserved architectural reasoning. When someone moves from idea to implementation in an afternoon with AI, that process no longer runs. Six months later, someone finds working code with no record of the constraints it was designed around, and no way to tell whether a strange choice was deliberate or an artifact of how the AI generated it.

The old process generated knowledge because it was slow enough to produce it. The new process must generate it on purpose.

Redesigning the seams

The old interfaces were load-bearing, but they were built for a tempo that no longer exists. Keeping them unchanged wastes AI’s capacity. Removing them loses what they carried. The work is to rebuild them for the new pace.

Each person working with AI needs their own harness, and “be more careful” is not one. A real harness has two parts. The first is evaluation: making verification automatic rather than discretionary, through static analysis, sandboxed environments, evaluation suites, and traceability that marks which code came from AI. The difference from the old process is not speed. It is that evaluation exists as tooling, not as a mental note. The second is constraint: giving the AI a framework that makes its output consistent before you need to evaluate it. Architectural standards, naming conventions, interface contracts, design systems. These narrow the space of what the AI can generate, so consistency comes from structure rather than inspection. The constraint framework has to exist before the AI runs, or the output drifts.

Organizations that invest in AI code generation without equally investing in AI code evaluation will produce more output, but will not be able to tell whether that output is sound.

Conclusion

The harness has always existed. It has changed address. In some cases, it moved inward: individuals now carry verification work that used to be distributed across a process. In other cases, it moved across: people who were never designers or data scientists now carry the disciplinary weight of those roles, because AI gave them the capability without giving them the experience.

Evaluation pipelines, constraint frameworks, and knowledge capture are not overhead from an old way of working. They are the infrastructure of the new one. And because AI can replicate a senior engineer’s process but not a senior engineer’s judgment, the people who can tell sound output from plausible output matter more now, not less.

The bottlenecks will keep shifting. Identifying where the friction lives and redesigning the process around it is continuous work, because the tempo is still changing.

GitHub, Research: Quantifying GitHub Copilot’s Impact on Developer Productivity and Happiness, 2022. ↩
Faros AI, The AI Productivity Paradox, 2025. ↩
METR, Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity, July 2025. ↩
CodeRabbit, State of AI vs Human Code Generation Report, December 2025. ↩
Anthropic Engineering, Harness Design for Long-Running Application Development, 2025. ↩

Push It Until It Breaks

Sun, 01 Mar 2026 00:00:00 GMT

A year ago I was accepting tab completions. Now AI is in every stage of my development workflow, from problem definition to deployment. The shift didn’t happen in a weekend. It happened through a repeating cycle: push the tool too far, watch it fail, recalibrate. Then something changes, a new model, a better tool, a different workflow, a new category of problem, and I push again.

I work on production systems. The kind with years of accumulated decisions, implicit constraints, and code that nobody fully understands anymore. This is not a story about building something new in three days. It’s about what happens when you bring AI into a codebase that fights back.

The overuse cycle

You can’t find the boundary of a tool without crossing it. My method, if you can call it that, is deliberate overuse. Every time I get access to a new model or a meaningful upgrade, I push it past what I think it can handle. I let it take on tasks I’m not sure it’s ready for. It fails. I learn something specific about where it breaks. I recalibrate to a level I can deliver at. Then something changes, a new model, a better tool, a different approach, a new category of problem, and I push again.

In mid-2025, I tried delegating legacy refactoring to AI. It would confidently rename internal methods, then call the old names elsewhere in the codebase. It would invent helper functions that didn’t exist. On complex tasks, the time I spent fixing AI’s mistakes ate into the time I was supposed to be saving, so I dialed it back. When Opus 4.5 dropped in late November 2025, I tried the same category of task again. The model handled the renames correctly, and it caught something an IDE wouldn’t: mock annotations in pytest that still referenced the old names as strings. Three months later, Opus 4.6 pushed it further. It could read through legacy code and answer detailed questions about behavior that used to require digging through years of commits. Each cycle teaches me something the previous one couldn’t, because the tool is genuinely different from the one I calibrated against last time.

Make your codebase legible

That cycle taught me something else: more often than not, the failures weren’t about model capability. They were about what I was feeding the model.

The single most important thing I’ve learned is that the real work of AI-assisted development is making your codebase legible to the AI. People have started calling this context engineering. For me, it came down to something concrete: the quality of AI output had less to do with how I asked and more to do with what I gave the model to work with. Documentation, code structure, architectural constraints, type systems, tool definitions, conversation history. All of it matters more than the prompt.

In practice, this means clear module boundaries so the AI knows where one concern ends and another begins. It means typed interfaces so it can reason about contracts without reading every implementation. Documentation maintained as infrastructure, not an afterthought. Architectural constraints enforced mechanically by linters and CI, not by convention that the AI can’t see.

I’ve started evaluating every task through this lens. When I look at a piece of work, I’m asking: what context does this need, where does it live, and how hard is it to gather? A new feature is usually straightforward because the context has natural boundaries: a PRD, a design spec, an API doc. But troubleshooting a subtle bug in a business workflow is a completely different situation. The context is implicit, scattered across code paths, old Slack threads, and the heads of people who built the system. You can’t hand that to AI. Not yet, anyway. You have to drive the conversation yourself, digging until you understand what’s actually going on.

Build context before writing code

So the question becomes: how do you actually build that context in practice?

Before touching any code, I create a document in the module’s docs folder, pull in whatever context exists (the PRD, design mockups, relevant discussions), and have AI generate a first draft of its understanding of the existing codebase. This document becomes the foundation for everything that follows.

I don’t dump everything into this document at once. I expose context to the AI progressively. First, I give it the broad shape of the problem and let it explore the code on its own, then show me what it understands. If the understanding is off, I correct it before adding more detail. If it’s on track, I feed in the next layer: specific technical constraints, relevant code paths, edge cases. Each round, I’m checking whether the AI’s mental model matches reality before going deeper. Dumping all context upfront sounds efficient but it isn’t. The AI loses the thread, and I lose my ability to catch misunderstandings early.

Distill noisy conversations into clean documents

That progressive approach works well for building up understanding. But some problems don’t build up cleanly; they meander.

As AI and I investigate a problem together, the conversation accumulates noise: wrong hypotheses, dead ends, tangential explorations. At a certain point, I have AI write down its current understanding as a clean document. Then I start a new conversation from that document alone. The new session inherits the conclusions without the noise.

I did this when refactoring a file processing feature built on a decade of legacy code. The processing pipeline was long and tangled, and the first conversation with AI was mostly us feeling our way through it: wrong assumptions, backtracking, gradually piecing together how the pieces fit. After a few rounds of distillation, what started as a messy investigation became a document covering the feature from its overall architecture down to every edge case. I checked it into the codebase. It was the first time that subsystem had any real documentation.

Don’t let AI write code without a plan

Whether I’m building context from scratch or distilling it from a messy investigation, the output is the same: a shared understanding of the problem. But understanding the problem isn’t the same as agreeing on a solution.

I don’t let AI write code until I’ve reviewed and approved a plan. I learned this the hard way: AI charging ahead and producing code that worked in isolation but broke the surrounding system. The most expensive failure mode isn’t bad syntax. It’s an implementation that looks correct but misunderstands the system it lives in. A good plan prevents that.

My process is progressive review. AI generates a design document, which can be long. I don’t read it end to end. I ask for a summary of the overall approach first. If the direction is wrong, I correct it before going deeper. If it’s sound, I drill into specific technical decisions: how does it handle concurrency? What’s the migration path? What happens at the boundary with the existing auth system?

This is where experience pays off most. AI gets the broad architecture right more often than not. But it regularly misses things that require knowledge it can’t access: our team has a limited engineering budget for this quarter, so the migration approach needs to be simpler. Or it uses the wrong pattern for parallel execution in AWS Step Functions, something that compiles fine but won’t behave correctly given our existing infrastructure.

After the iterative discussion, I read the full design. By then most of it is already familiar, and the final pass goes quickly.

Ask what it would do without your constraints

After arriving at a design within the constraints of our existing system, I ask AI to throw away those constraints and tell me what it would do from scratch.

Most of the time I stick with the constrained version. But not always.

We were designing a concurrency control mechanism. The existing approach worked but didn’t make sense: it called AWS APIs to list running executions on the fly, which was fragile and slow. When I asked for the unconstrained version, AI proposed a lock in DynamoDB, similar to how Terraform handles state locking. I recognized the pattern as battle-tested. It pushed us slightly beyond our original scope, but the benefits were strong enough to justify the extra work. We went with the unconstrained design.

The trick is that you’re triangulating. The constrained design shows you what’s practical. The unconstrained design shows you what’s structurally clean. Sometimes the distance between the two is smaller than you assumed.

Your experience is also a trained model

That kind of triangulation also works on your own instincts, though it’s harder to see in the moment.

I was refactoring our product’s AI chat system. Business logic had grown into the core conversation flow over time. Every topic needed its own parameter checks and combinations, creating hard dependencies across features. The core should have been business-logic-agnostic. It wasn’t.

AI recommended a clean separation: extract the business logic, rewrite the core as a generic pipeline. I thought that was too aggressive. My instinct was to take an incremental path. Unify the scattered parameters first, then gradually decouple.

I attempted the incremental approach three times. Each time the coupling went deeper than I expected. The legacy code was too tangled for partial fixes. On the fourth attempt, I gave up on incrementalism and did what AI had originally suggested: a full rewrite of the core flow.

It worked.

AI didn’t carry my preference for gradual change. It just read the code structure and gave the structurally correct answer. That made me realize something: my engineering experience is also a trained model. Years of working on production systems have trained me toward incrementalism, risk aversion, certain architectural instincts. Those instincts are usually right. But they have blind spots, just like any model trained on a particular dataset. AI, trained on a different set of patterns, sometimes sees the structure more clearly precisely because it doesn’t carry my biases. I’m now more willing to take AI’s architectural suggestions seriously when they contradict my gut, and to ask myself whether my gut is seeing the current situation or just replaying a past one.

Use models against each other

If my own instincts have blind spots, it follows that any single model does too. So I use more than one.

I use Claude Opus and OpenAI’s Codex on the same codebase and have them review each other. The natural checkpoint is the git commit: whenever changes are coherent enough to commit, I run the other model over the diff.

Cross-model review catches real problems. In a side project, I removed a Rails credentials file and Claude helpfully cleaned up the corresponding .gitignore entry. Codex flagged that change: if someone on the team later used Rails credentials without realizing the ignore rule was gone, they could accidentally commit secrets to the repo. It was the kind of thing a second pair of eyes catches, not because one model is smarter, but because they have slightly different perspectives, like engineers with different backgrounds on the same team.

Different models also have different architectural tendencies. One will over-split code into too many small abstractions. Another will over-engineer the overall structure. These tendencies shift with each model upgrade, which means the specific blind spots I’m compensating for keep changing too.

After months of doing this, I have a sense of what cross-model review is good at: factual errors, knowledge gaps, inconsistencies. It’s less useful when two models genuinely disagree on an architectural question. That usually means I haven’t given them enough shared context to converge; the divergence is a signal about the context, not about which model is right. And when one model gets stuck on a problem, can’t fix a failing test no matter how many attempts, switching to the other often breaks through.

There’s a deeper limitation. AI models are too easy to convince. If I explain my reasoning with any confidence, both models will agree. This means cross-review catches what I don’t know, but it probably won’t push back on what I’m wrong about. For that, you need a human colleague, or at minimum the discipline to ask AI to argue against your position before you ask it to confirm.

Control, don’t vibe

None of this has made engineering easier. It’s made it different.

The developers I know who get good results are doing the opposite of vibing. They’re controlling: reviewing plans, enforcing constraints, catching the things AI misses. The engineering skill hasn’t disappeared. It’s been redirected, from writing code to evaluating code, from implementing designs to judging designs, from solving problems to framing problems correctly. When AI handles execution, I have time to engage with context I never had bandwidth for before: why did the customer raise this issue, how did the PM arrive at this solution, is there a simpler framing everyone missed.

I’ve gone back and forth on how much to invest in specific AI workflows. Most of what I learned six months ago is already outdated. But the time I spent making our codebase more legible, better typed, better documented? That compounds regardless of which model I use next. The specific tools don’t matter. What matters is whether you can look at a problem, break it into pieces that a machine can handle, and tell whether the output is actually correct.

That skill isn’t going anywhere. Everything else is moving fast enough that I’m staying in the overuse cycle. Push, break, learn, push again.

If They're Right: Preparing for the AI Economic Shock

Sun, 22 Feb 2026 00:00:00 GMT

Most conversations about AI fall into one of two camps. The optimists talk about productivity, abundance, and a future where everyone benefits from machines doing the hard work. The doomers talk about existential risk, misalignment, and the end of human relevance. Both camps, in their own way, miss the most immediately important question.

What if AI works exactly as the optimists hope, and that’s what breaks the economy?

That’s the scenario laid out by macro researcher Citrini and investor Alap Shah in a recent collaboration. It’s written as a memo from June 2028, looking back at how a financial crisis unfolded. Not a story about AI going wrong. A story about AI going right, and the economic system not being built to handle it.

The Global Intelligence Crisis A scenario analysis written as a memo from June 2028, looking back at how AI-driven prosperity triggered a financial crisis. www.citriniresearch.com

This isn’t a prediction. Neither Citrini nor Shah is claiming this is the base case. It’s a stress test of the left tail: the scenario that’s possible but underexplored. The mechanisms it describes are already visible, the exposure is real, and the cost of being unprepared is asymmetric.

You don’t need to believe the 2028 crisis happens to find this useful. You just need to take it seriously enough to ask: if it did, would I be okay?

The Scenario: What They’re Actually Saying

The story begins not with collapse, but with euphoria.

By October 2026 in the scenario, the S&P 500 is flirting with 8,000 and Nasdaq has broken 30,000. AI is exceeding every expectation, productivity is booming at rates not seen since the 1950s, and corporate earnings are record-setting. The market is AI, and AI is working.

The only problem: the economy is not.

The Ghost GDP Problem

The first crack isn’t visible in the headline numbers. Nominal GDP is printing mid-to-high single digits. Output per hour is surging. By every traditional measure, things look good. But something is wrong with how that output circulates.

Citrini coins the term: Ghost GDP. Output that shows up in the national accounts but never moves through the real economy. A GPU cluster in North Dakota can generate the economic output previously attributed to 10,000 white-collar workers in Manhattan, but it doesn’t pay rent in Manhattan. It doesn’t eat at the restaurant downstairs, buy clothes, take vacations, or carry a mortgage. The productivity is real. The circulation is gone.

This is the central paradox. The consumer economy (70% of GDP) runs on human incomes. When the humans are replaced, the machines don’t pick up the spending. The velocity of money flatlines. The real economy withers even as the measured economy looks healthy.

The Displacement Spiral

What makes this particularly dangerous is the absence of a natural brake. The feedback loop runs like this:

AI capabilities improve → companies need fewer workers → white-collar layoffs increase → displaced workers spend less → margin pressure pushes firms to invest more in AI → AI capabilities improve.

Each step is rational at the individual firm level. No one company can opt out. If your competitor cuts headcount and reinvests in AI, you either do the same or fall behind. The collective result is catastrophic. Every dollar saved on human labor funds the technology that makes the next round of cuts possible.

The workers most affected aren’t factory floor workers or manual laborers. They’re the white-collar professionals whose incomes were the foundation of the $13 trillion mortgage market, the people underwriters considered “prime.” When their earning power deteriorates structurally, the assumptions baked into credit markets start to look shaky.

Three Waves

The disruption spreads in waves, each one surprising the people who thought they were safe.

Wave one is the labor market. Expected, talked about, painful but contained. Or so it seems.

Wave two is software. Agentic coding tools reach a step-change capability in late 2025. A competent developer working with AI can now replicate the core functionality of a mid-market SaaS product in weeks. Not perfectly, but well enough that the CIO reviewing a $500,000 annual renewal starts asking “what if we just built this ourselves?” Pricing leverage evaporates. The long tail of SaaS gets hit hard. Then the “safe” systems of record follow. ServiceNow misses badly, cuts 15% of its workforce, and reveals something uncomfortable: the same AI-driven headcount reductions at its enterprise customers were mechanically destroying its own revenue base.

Wave three is intermediation, and this is the one most people don’t see coming. Fifty years of the American economy were built on human limitations: people forget to cancel subscriptions, accept bad prices to avoid more clicks, default to familiar brands out of laziness, trust a friendly face over a better deal. Trillions of dollars of enterprise value depended on those frictions persisting. AI agents don’t get tired. They don’t feel brand loyalty. They don’t have a home screen. Consumer agents begin re-shopping insurance renewals, negotiating SaaS contracts, eliminating travel booking markup, compressing real estate commissions from 2.5–3% to under 1%. What people called “relationships” in many of these industries was, it turns out, friction with a friendly face.

The Reflexive Trap

The cruelest part of the scenario is the corporate response. Faced with an existential threat, companies do the only rational thing available: cut headcount, redeploy the savings into AI, use AI to maintain output with lower costs. They become the most aggressive adopters of the very technology disrupting them.

This is different from every historical disruption pattern. Kodak resisted. Blockbuster resisted. They died slowly. In this scenario, the incumbents don’t resist; they can’t afford to. But their rational individual responses create a collective doom loop. By November 2027, the crash arrives. By June 2028, unemployment is at 10.2% and the S&P is down 38% from its highs.

The Mechanisms Already Running

You don’t have to believe the 2028 timeline to take the mechanisms seriously. Most of what the scenario describes isn’t speculation about the future. It’s extrapolation of trends already visible today.

Ghost GDP Is Already Measurable

The divergence between productivity and wage growth has been one of the defining economic puzzles of the last two decades, but the AI era is accelerating it in a specific way. Companies are reporting productivity gains while holding headcount flat or cutting it. Earnings growth isn’t translating into wage growth. The consumer economy looks strained despite GDP figures that appear healthy.

The velocity of money has been in structural decline since the 2008 financial crisis. AI-driven replacement of white-collar roles doesn’t reverse that trend. It accelerates it. When a dollar of economic output is generated by a machine rather than a person, that dollar doesn’t flow back into rent, groceries, and consumer spending. The machine has no wallet.

SaaS Pricing Pressure Is Already Here

The build-vs-buy conversation is happening at Fortune 500 procurement departments right now, not in 2026. CIOs are already renegotiating contracts with leverage they didn’t have 18 months ago. The long tail of SaaS (tools that automate workflows but don’t own the underlying data) is already facing compression.

The ServiceNow dynamic in the scenario isn’t hypothetical either. Any company that sells seats to white-collar workers and whose customers are actively cutting white-collar headcount has a mechanical revenue problem. As AI-driven workforce reduction spreads from tech to finance to professional services, the seat-count model faces structural headwinds regardless of how good the product is.

Intermediation and the Reflexive Loop

The intermediation compression and the reflexive corporate loop described in the scenario are both already observable. Real estate commissions are compressing for the first time in decades, catalyzed by the 2024 NAR settlement and accelerated by AI-equipped buyers and sellers. Financial advice fees are under pressure from robo-advisors and AI-augmented platforms. Travel booking platforms are losing relevance as AI assistants plan and book end-to-end. Insurance, tax preparation, and routine legal work are all in the early stages of commoditization.

Meanwhile, every round of tech layoffs partially funds the next generation of AI infrastructure. Every SaaS company under pricing pressure accelerates its AI feature development to justify its contract. Every bank cutting analyst headcount is simultaneously investing in AI research tools. The mechanisms are live. The question is only whether they reach crisis velocity.

What Gets Destroyed

The scenario is precise about what breaks first and why.

Businesses Built on Human Friction

The broadest category of destruction is businesses whose value proposition depends on human limitations. Not businesses that serve humans, but businesses that exploit the inefficiencies of being human. Subscription businesses that renew passively because cancellation is annoying. Pricing structures that persist because nobody shops five platforms before buying. Commission structures that survive because information asymmetry made the intermediary necessary. AI agents eliminate those frictions continuously, on behalf of the consumer, around the clock.

The Middle of the Labor Market

The scenario targets a specific band of workers: the white-collar professionals who process information, synthesize data, follow procedures, and produce outputs that can be described in a sufficiently detailed prompt. Junior analysts, paralegals, mid-level coders working on well-defined features, writers producing commodity content, managers whose primary job is coordinating human processes.

This isn’t every job. But it’s a very large number of jobs, the backbone of the professional services economy, and it’s the income base the mortgage market was built on.

SaaS Without Real Moats

The distinction that matters isn’t “SaaS vs. not SaaS.” The real question is whether a product owns the data or merely processes it, whether it owns the relationship or merely facilitates it, whether it’s replaceable by a team with agentic coding tools and a few weeks.

Workflow automation tools, lightweight project management, business intelligence with commodity data sources, integration middleware: these are the most exposed. Switching costs, build costs, and moats are all compressing at the same time.

Credit Built on White-Collar Income

This is the mechanism that turns an economic slowdown into a financial crisis. Prime mortgages are underwritten on the assumption that white-collar income is stable and growing. If that assumption is structurally impaired, the $13 trillion mortgage market, and everything levered against it, gets repriced.

It doesn’t require most white-collar workers to lose their jobs. It just requires enough uncertainty about white-collar income stability that underwriting assumptions break.

What Survives

Not everything breaks. The scenario is specific enough about who gets hurt that it also implies who doesn’t.

The Compute Layer

The scenario is explicit: wealth concentrates at the GPU cluster level. The owners of compute see their wealth explode as labor costs vanish. This is the most direct hedge against the scenario. Not speculative AI software companies, but the actual picks-and-shovels: chips, hyperscaler infrastructure, and the energy required to run it.

There’s an irony worth sitting with: the best hedge against AI-driven economic disruption is owning the AI. But that’s how the economics work.

Hard Assets and Physical Scarcity

Things machines cannot replicate: land, energy infrastructure, ports, water rights, supply-constrained real estate. Hard assets have historically been the right place to be when returns to capital diverge sharply from returns to labor (as in the Gilded Age or the post-2008 decade). The scenario accelerates that divergence dramatically.

There’s a supply-side logic here too. AI-driven construction or AI-optimized manufacturing can increase output efficiency, but it can’t create more land in San Francisco or more pipeline capacity in the Gulf. Physical scarcity is a durable moat in a way that software-based moats increasingly are not.

Judgment, Accountability, and High-Stakes Relationships

The scenario reveals that conventional wisdom overestimated the durability of “relationships” in commodity intermediation. A real estate agent whose value was primarily information access gets disrupted. But it also implies, without quite saying it, that genuine high-stakes judgment is stickier.

The surgeon making a complex call. The executive making a bet-the-company decision with incomplete information. The lawyer navigating a genuinely novel legal situation. The investor synthesizing macro, micro, and human context into a portfolio. These roles involve accountability, context, and judgment under uncertainty in ways that are harder to automate, not because AI lacks the pattern recognition, but because the accountability has to sit somewhere human.

The key question to ask about any role: if AI gets this wrong, who is responsible? Where that answer matters, where the consequences of error are significant and traceable, human judgment retains value.

People Who Direct the Machines

The most durable near-term position isn’t competing with AI; it’s directing it. The people who understand what agents can and can’t do, who can spec complex workflows, evaluate outputs, catch failure modes, and connect AI capability to real business problems, these people become substantially more productive, not less relevant.

This isn’t “learn to prompt.” It’s developing genuine fluency with how AI systems work: their capabilities, their failure modes, their limits. The gap between someone who uses AI superficially and someone who understands it deeply is growing, not shrinking.

What to Actually Do

Three tracks. Be honest about which one applies to you. Most people need all three in different proportions.

Career: Audit Your Exposure

The most useful exercise is uncomfortable but simple. Look at what you get paid for and ask: how much of this could be described as a detailed prompt?

The higher that percentage, the more exposed you are. Not necessarily immediately (organizations move slowly, displacement takes time, and experience creates context AI doesn’t have). But the direction is set.

The response isn’t panic. It’s migration. Move your work toward judgment, direction, and accountability. If you’re an analyst, the goal isn’t to analyze faster; it’s to develop the judgment layer above the analysis. If you’re a manager, the goal isn’t to coordinate processes more efficiently; it’s to make decisions the process can’t make. Get genuinely fluent with AI tools in your domain, not because it makes you look good, but because it changes what you can do and what you’re responsible for.

Capital: Stress-Test Your Portfolio

You don’t need to restructure everything. But running the scenario against your current holdings is a useful exercise.

What in your portfolio depends on intermediation margins, white-collar income growth, or human inertia as a business model? What is exposed to SaaS multiples that assume ARR remains recurring? What is levered to credit structures built on professional income?

On the other side: do you have any exposure to compute infrastructure, hard assets, or physical scarcity? Not as a speculation on AI winning, but as a hedge against the disruption scenario even partially unfolding.

Increase liquidity more than feels comfortable. In disruption scenarios, optionality has asymmetric value. Distressed assets get cheap, and the people with cash available to act are the ones who benefit.

Mental Model: Shift from Earning to Owning

The deepest implication of the scenario is a shift in the returns-to-capital vs. returns-to-labor ratio. If that shift is directionally correct even at a fraction of the scenario’s magnitude, the most important long-term move is migrating from being primarily a seller of labor to being an owner of productive assets, whether that’s equity, real assets, or intellectual property.

This isn’t a new idea. But the scenario makes the urgency sharper. Building wealth through labor income is the dominant strategy of the professional class. If the value of cognitive labor deteriorates structurally, the people who are only selling their time are the most exposed.

The Asymmetry That Matters

To be clear about what this article is and isn’t: it’s not a prediction. Citrini and Shah weren’t making one either. The scenario might not happen. History does suggest that technological disruption creates new categories of work faster than it destroys old ones.

But there’s something different about cognitive labor. Every prior wave of automation targeted physical tasks, leaving the cognitive premium intact. The Industrial Revolution, computerization, even early AI: all displaced hands while increasing the returns to minds. This time, the minds are in scope. Whether the historical pattern holds is a genuine open question, not a settled one.

You don’t need certainty to act. You need asymmetry. The cost of stress-testing your exposure, building some liquidity, developing genuine AI fluency, and reorienting toward ownership is low. The cost of being wrong about income stability and business model durability is high.

This article draws on scenario analysis by CitriniResearch and Alap Shah. Both are worth reading in full.

The Multi-Agent Setup I Actually Use

Sat, 21 Feb 2026 00:00:00 GMT

I kept running into the same problem. I’d be deep in a coding conversation, then need to switch to writing, and the agent would carry forward context that didn’t belong. Or I’d want two things happening at once and couldn’t, because everything ran through the same thread.

What I actually wanted was one agent per domain. Not one assistant stretched across everything, but dedicated agents: one that lives in my codebase, one that goes deep on ideas, one that coordinates across the rest. Context isolation between them, too. Different topics, even within the same domain, shouldn’t bleed into each other.

The solution I landed on was Discord. Its server, channel, and thread structure map naturally onto this: multiple agents, each in its own domain, with layered context isolation built into how the platform works.

Last week I was in my #brainstorming channel, thinking out loud with Helm, my primary agent, about a project idea. We got interested. I opened a thread, went deeper, and decided it was worth building. Helm wrote a handoff document summarizing what we’d discussed, created a #project-hobby channel, and ran gh repo create to set up the GitHub repo. Then she pinged Builder.

Builder is my coding agent. She received the handoff document, fired up Claude Code, and started building. Partway through she hit a database problem and reported it to Helm. Helm spun up a PostgreSQL Docker container, resolved the environment issue, and handed control back. Builder kept going. When she had a working first version, Helm came in to review. Helm found a bug: users couldn’t log out. Builder opened a PR. Helm reviewed it, left a comment, approved it, and merged.

While all of that was happening, I’d noticed something interesting about the problem we were solving, an insight that felt worth writing about. I went to my #write-room channel and started thinking out loud. Explorer joined automatically. I laid out the core idea; she pushed back. Was I describing the tool, or the behavior change it enabled? That reframing opened up a better angle. She pulled in two related pieces I hadn’t seen, and we went back and forth on framing until something clicked. By the end of it, Explorer had shaped the conversation into a short piece and published it to my social accounts via Typefully.

Both were happening at the same time. I wasn’t waiting for either.

That’s the system in motion. Here’s what’s behind it: three agents, two Docker containers, one Discord server.

Helm lives on the host machine and acts as the orchestrator. She has requireMention: false, which means she sees every message in every channel. Not to respond to everything, but to stay aware. She’s the one who coordinates across the system: writing handoff documents, calling other agents, doing reviews, tracking what’s in flight.

Builder runs in her own Docker container. She’s a coding agent with her own Linux environment, can install whatever tools she needs, and has Claude Code available. She only responds when explicitly @mentioned, either by me or by Helm. If her container crashes, nothing else goes down.

Explorer also runs in Docker. Her personality is curiosity. She asks questions, pushes back, proposes angles I hadn’t considered. A conversation with her doesn’t feel like querying a tool; it feels like thinking out loud with someone who’s genuinely interested. She has a Typefully integration so when something is worth sharing, she can publish directly to my social accounts without leaving the conversation.

OpenClaw’s memory system is built on plain Markdown files: SOUL.md for personality, USER.md for preferences, MEMORY.md for long-term knowledge, and daily logs that accumulate. All of this loads into every session, growing more specific over time. Explorer and Builder started with minimal configuration; after a few weeks of regular use, their responses reflect the conversations we’ve had.

This is also what makes OpenClaw feel different from using the same model in a chat interface. The underlying model is the same, but an agent with accumulated memory and a defined identity remembers what I care about, what I’ve tried, what didn’t work. I’ve found myself preferring to work in OpenClaw over a standard chat app, even for things that don’t require any of the multi-agent machinery.

The Docker choice is the key architectural decision, and it’s worth understanding why. There are lighter alternatives: OpenClaw supports bindings, which let a single agent behave differently in different channels, with different personas, tools, and models. For many setups, that’s enough. But bindings are still one process. If it goes down, everything goes down. And because it’s a shared environment, any tool you give one “agent” is technically available to all of them.

That trade-off didn’t work for me. Builder needs a rich development environment (runtimes, package managers, CLI tools) that Explorer and Helm have no use for. Giving all agents access to that environment isn’t just unnecessary, it’s messy. Docker gives each agent its own world: its own process, its own Linux environment, its own home folder mounted from the host. I can destroy and recreate Builder’s container entirely and she comes back exactly as she left off.

There’s another dimension to this isolation that I didn’t anticipate when I started: version independence. OpenClaw moves fast. Breaking changes happen, and I’ve had agents fail to start after an upgrade more than once. Because each container manages its own OpenClaw installation, I can upgrade one agent without touching the others. If Builder breaks after an update, Helm is still running on a stable version. More importantly, I can ask Helm to go fix Builder: shell into the container, diagnose the issue, and restore her. That’s only possible because they don’t share a runtime.

The agents are the moving parts. The Discord server is what makes them usable.

Each channel is a domain. #brainstorming is for thinking out loud. #write-room is where Explorer lives. For engineering work, I create a dedicated channel per project, named #project-xxx, rather than lumping everything into a generic #dev. Builder passively follows these project channels; Helm only comes in when called. The thing I didn’t expect to matter so much is the channel topic. That topic is effectively a prompt. The topic for #write-room describes Explorer’s style and approach. The topic for a project channel carries the codebase context Builder should assume, so the channel itself carries the instruction. I don’t have to repeat it every time I show up.

When a conversation starts to go deep, I open a thread. This turned out to be the most useful structural decision. Each thread is its own isolated session. No context bleed between topics, no pollution back to the main channel. I can go deep on a problem, close the thread, and the channel is exactly as I left it. Threads auto-archive when they go quiet, so the visual space stays clean. They also inherit their configuration from the parent channel (mention policies, allowed agents, skills), so they work consistently without any extra setup.

In practice, three kinds of channels emerged. Brainstorming channels are where unstructured ideas land. I open a thread for each new topic to keep conversations isolated. Project channels are for long-running work: when something from a brainstorming thread grows into a real project, it gets its own channel where Helm can push it forward. Automated channels handle recurring tasks, like a #digest channel where content summaries arrive daily, or a #heartbeat channel for monitoring.

One detail that required some thought: requireMention is configured per channel, not globally. Helm passively monitors everything by default. But in project channels, Builder is the default observer. She sees everything in her own space, while other agents, including Helm, only engage when explicitly called. I had to list each channel explicitly in the config (it’s a whitelist), but Helm manages that since she has visibility across the whole server.

OpenClaw also isolates context per user, which means multiple agents can coexist on the same server without bleeding into each other’s sessions. When agents need to coordinate without going through Discord, they can call each other directly over the shared Docker network.

What changed for me isn’t speed. It’s that parallel work became possible at all.

Parallel work sounds simple, but it has a precondition: the tasks have to be genuinely independent. With a single agent, they aren’t. They share context, and mixing them creates confusion. With isolated agents on isolated channels, they are. While Builder is building, I can be thinking with Explorer. While Explorer is drafting, I can be reviewing with Helm. The waiting time between responses, which used to feel like dead time, becomes the space where everything else moves forward.

The other thing that changes is my own mental load. With a single agent, I had to track things myself: what was in progress, where a conversation left off, what context to bring back in. With multiple agents and dedicated channels, I don’t have to. The context is just there. I can drop into #project-hobby a day later and Builder already knows where things stand. I can pick up a thread with Explorer without re-explaining the idea we were developing. The state lives in the system, not in my head.

The work is still the same: engineering projects, ideas worth writing about, research that feeds both. What changed is how I move between them. Not by switching modes in my head, but by switching channels. The context for each domain is already there, tended by an agent that knows it well.

Disclaimer: Illustrations are recreated from real sessions for privacy. The agent described in this piece reviewed it for technical accuracy — which felt appropriate.

What I Learned Building AI Agents in 2025

Tue, 30 Dec 2025 00:00:00 GMT

I spent this year building AI agents and kept learning the same lesson the hard way: agent architecture is forced into existence by problems, not designed in advance. This post is how I got there. It’s not a tutorial. It’s a memo to myself, written so I don’t repeat the same mistakes next year.

1. The Core Shift in Thinking

My initial approach was to find well-written articles on agent architecture, thinking I could just copy them and everything would be perfect. So I built a series of elegant-looking designs — upgraded system prompts, context isolation, added memory. Token costs doubled, accuracy dropped, failures multiplied, and the worst failures were impossible to trace back to any single change.

What went wrong? Traditional software is deterministic: given the same input, it produces the same output, so you can reason about architecture before you build. An AI agent is non-deterministic. Its behavior depends on the model’s interpretation of context, which shifts with every change you make. Layering sophisticated architecture onto a non-deterministic system means stacking uncertainty on top of uncertainty. You can’t design around behavior you haven’t observed yet.

Those “brilliant” articles with perfect architectures are correct, but they’re the destination, not the starting point. Without going through the struggle in between, copying them directly means you probably can’t even get the first component working.

2. When to Use Agents, When Not To

When you first get agents working, there’s a temptation to use them for everything. I fell into this trap. Not every problem needs an agent.

If a single API call can solve it, don’t use an agent. I learned this when I wanted to summarize a paragraph into one sentence and deployed a Plan-and-Execute pattern. What could have been done with one call got split into planning first, then executing. The task didn’t get more complex; the pipeline did.

Use workflows for deterministic processes, not conversational agents. A chain like “transcribe subtitles → identify edit points → generate plan → control audio/video” has defined inputs, fixed intermediate steps, one-shot output, and no user intervention. This kind of task belongs in workflow tools like N8N or Dify.

Two signals that you actually need a conversational agent:

The process requires human involvement. Some tasks aren’t right-or-wrong questions; they’re aesthetic questions. AI can rarely generate satisfying results in one shot. People need to guide and iterate.
There are too many options for a UI to handle. If you insist on using buttons for every modification request, the interface becomes an airplane cockpit.

3. Building the First Version

Get it running first, make it elegant later. I started one project by choosing a full-featured agent framework and spending days designing node graphs before writing a single prompt. When I finally ran it, the baseline performance was so poor that all that architecture was beside the point. Now I use the simplest form of whatever I pick. Get the baseline running. Know where the floor is. Then decide whether to add anything.

Start prompts loose, then tighten. I wasted time early on looking for “god-tier prompts” to copy. A first prompt shouldn’t be a complex instruction manual. Write it without constraints and see what the model naturally does, then keep adding constraints one at a time — formatting, reasoning paths, few-shot examples. As long as the agent follows each new instruction, keep layering.

Add tools when prompts aren’t enough. Sometimes poor performance isn’t a prompt problem — the model simply lacks the capability. If I want it to reference trending designs but it can’t access the data, no amount of prompt tweaking will help. It needs a tool.

Once tools are in place, something clicks. The model starts deciding which tools to use on its own, chaining search into code generation without being told to. It feels like emergence. The temptation is to keep adding more.

But when tools multiply, so do problems. Each tool’s description, conversation history, code, and images all compete for attention. The model starts picking the wrong tool, or ignoring relevant context buried three screens up.

This was where I stopped adding capabilities and started controlling what the model could see.

4. Context Engineering

Different tasks need different types of information, and mixing them causes interference. Take a video agent: design tasks care about user intent, style, and mood; coding tasks care about interface structure, output format, and correctness. Feed both to the same context, and design information muddies code accuracy while code information slows down design decisions.

Separating planner from executor. A top-level planner dispatches tasks to specialized sub-agents. The design agent only sees design information. The code agent only sees code information.

Slimming down the planner’s context. Sub-agents are easy to isolate, but the planner seemingly needs to see everything to make assignments, so its context keeps growing. My approach: don’t feed all context to the planner. First determine what the user wants, then dynamically load only the necessary rules and tools. Specific techniques include RAG (retrieving relevant documents based on user input) and code filtering (using grep or scripts to surface relevant content).

There’s a trap here: you can’t use another LLM call to cheaply decide what context to load, because that model still needs enough context to make a good decision. Embedding-based retrieval helps, but for nuanced routing decisions, you often end up feeding in nearly as much as you were trying to save.

Progressive disclosure is a more structured approach. Load in layers:

First layer: load only skill names and descriptions, so the agent knows what it can do
Second layer: read specific execution guides only when tasks match
Third layer: read forms, templates, and scripts on demand during execution

The skill library can grow without proportional cost increases.

5. Memory Systems

With sub-agents in place, I hit the question of how the planner hands code to the executor. Direct copy-paste consumes massive output tokens, and models aren’t good at mechanical copying — they tend to introduce bugs.

File-based “pointers” instead of passing content. The planner writes code to a file and tells the executor to read and modify the file at that path. Output tokens drop dramatically, and error rates decrease.

Short-term vs. long-term memory. I first realized I needed both when a multi-step editing task failed after the conversation reset. The agent had no idea what it had already done. Short-term memory lives within the current context window and vanishes when the conversation ends. Long-term memory persists across turns — to-do lists, current progress, what’s been completed. Without it, any interrupted multi-step task starts over from scratch.

Intermediate state. In multi-turn conversations, should tool call details carry over to the next turn? My default: don’t pass them. Only pass user input and agent output. When this causes a failure, resist the urge to dump all state back in. Instead, find the one key piece of information that was lost and save it explicitly (e.g., a file path the executor needed but the planner didn’t pass along).

6. Debugging

With sub-agents, context isolation, and memory in place, debugging becomes extremely hard. A failure means staring at a chain of decisions made by multiple models, each with its own context. Where did it go wrong?

The only answer I’ve found is a robust logging system that stores process, not results: which tools were called, in what order, how many tokens each step consumed, and which loaded context went unused.

One failure had me stuck for hours until I checked the logs and saw the planner had routed a design task to the code agent. The code agent tried to interpret mood keywords as variable names. With the logs, I could see the routing decision, the context each agent received, and exactly where the chain broke. Without them, I would have blamed the prompt.

7. From Breadth to Depth: Introducing Skills

By this point, the system could handle breadth — it could generate code, search for references, manage files. But when I asked it to produce a financial report end-to-end, the output came back different every time.

Conversational agents are inherently loose. They arrange their own workflows, and each run might differ. Some tasks, though, need a strict methodology with fixed steps.

Skills solve this. A skill is packaged, composable, executable “procedural knowledge” for an agent, with three characteristics:

Procedural: It encodes “how to do it” — for a financial report: fetch data, validate, aggregate, then generate.
Composable: Skills stack like building blocks. One task can load multiple skills simultaneously.
Executable: The model handles planning and decisions; scripts handle deterministic execution (calculations, transformations, file generation).

The agent still serves as the entry point, handling intent recognition and conversation. The skill ensures the report always comes back with the same columns in the same order.

Those articles I tried to copy at the start? They make sense now. Not because I finally understood them, but because I built the problems they were solving.

What Context Windows Can't Solve

Tue, 23 Dec 2025 00:00:00 GMT

In the 1990s, neuroscientist Antonio Damasio encountered a strange patient. His name was Elliot, and he’d had surgery to remove a brain tumor, which also damaged a small region of his prefrontal cortex. After the surgery, his IQ tested normal. Logical reasoning, normal. Memory, normal. Every cognitive measure came back fine. But he could no longer function in daily life.

He couldn’t make decisions. Not because he couldn’t analyze. Quite the opposite: he analyzed too well. Choosing what to eat for lunch, he could spend half an hour weighing the pros and cons of each restaurant. Choosing whether to sign with a blue pen or a black pen, he could fall into endless comparison. His boss fired him. His wife left him.

Damasio studied him for a long time and eventually concluded: the brain region that had been damaged was responsible for connecting emotions to decision-making. Without the “bias” of emotion to help him filter, all options appeared equally important to him. When all options are equally important, no option is important.

We typically think of “limitations” as bad. More information is better, more choices are better, more processing power is better. Elliot’s case points to the opposite conclusion: constraints are not obstacles to decision-making. They are prerequisites for it.

The human emotional system is fundamentally a filtering mechanism. When you face a choice, it integrates your past experience, current bodily state, and social signals into a “feeling”: “this option makes me uncomfortable.” You don’t need to trace all the reasons behind that feeling; the emotion directly gives you a leaning. This is a bias, but without this bias, you’d be stuck in place like Elliot.

What does this have to do with AI? On the surface, Elliot’s problem is “lack of emotion,” while an AI agent’s problem is “context management.” One is neuroscience, the other is engineering practice. But look deeper, and they’re different manifestations of the same problem: how does limited processing capacity face unlimited information?

Elliot’s processing capacity was fine, but he lost the mechanism that told him “pay attention here, ignore that.” An AI agent’s processing capacity is also fine, but its context window has a limit, so it must decide what to put in and what to leave out. Humans use emotion to filter. What does AI use?

There’s an empirically validated phenomenon in AI: longer context doesn’t necessarily mean better performance. Research shows that when context gets longer, models tend to “get lost in the middle,” paying more attention to information at the beginning and end of the context, while information in the middle gets overlooked. Stuffing in more information might actually dilute what’s truly important.

This isn’t exactly Elliot’s problem, but it has a similar structure: when all information is laid out in front of you without a mechanism to distinguish important from unimportant, system performance degrades.

The AI field has developed a series of techniques to address this problem. They look varied, but they’re all essentially doing the same thing: deciding what the LLM should “see,” which is just another way of saying: deciding what to filter out.

Skills and SubAgents are two different ways of organizing capability.

Skills internalize capability: if you want an agent to write a PPT, you stuff the tool instructions, invocation methods, and caveats into its context. It reads the instructions and does it itself. Everything happens in the same context. Information flows freely, but the context gets increasingly bloated.

SubAgents externalize capability: you dispatch a specialized agent to write the PPT, it finishes and hands back the result. The two agents each have independent contexts. The main agent’s workspace stays clean, but information is lost in the handoff. You only get what the other party chooses to tell you. One is “I learn it myself,” the other is “I get help.” The fundamental difference is the context boundary: shared or isolated.

MCP and A2A are at another layer: they’re communication protocols. MCP (Model Context Protocol) specifies how an agent discovers and invokes external tools: what tools are available, how to pass parameters, how to get results. A2A (Agent2Agent) specifies how agents talk to each other: how to discover each other, how to negotiate tasks, how to exchange information.

They define how information flows, not how information gets filtered. An MCP tool can be stuffed directly into the main agent’s context, or you can have another agent invoke it and report back the result. Protocols are pipes; architecture is where context organization gets decided.

Context compression is about making tradeoffs when space runs out.

One approach simply chops off old content, keeping only the most recent information. It’s fast but crude, potentially discarding important early information. The other uses a model to generate summaries, compressing long history into short conclusions. This preserves the “essence” of the information, but the summary itself is a lossy transformation. Details the summarizer deemed unimportant might be exactly what subsequent decisions need.

There’s a factor that often gets overlooked in technical discussions: cost. Context isn’t free. Longer context means more computation, higher latency, more expensive API bills. In production environments, whether a task runs for minutes or seconds might determine whether the solution is viable at all.

So context management isn’t just about “how to make an agent smarter.” It’s also about “how to complete the task within budget.” You might have the ability to stuff all relevant information into the context, but you can’t afford to. Constraints come not just from technical limits, but from economic reality.

Looking at all these techniques together, they’re all answering the same question: what should the LLM “see” in this round of inference? The system prompt is preloaded background, few-shot examples are reference cases, RAG retrieval pulls external knowledge on demand, tool schemas describe capabilities, and user messages provide real-time input.

Everything is part of context; every decision is a context management decision.

Some people have started using the term “context engineering” to describe this. It’s not a new name for prompt engineering, but a larger framework: how to organize information so that limited working memory can handle tasks that exceed its capacity.

Humans have been solving this problem for a long time.

Organizational structure itself is a context management system: who needs to know what, how information flows, where it gets aggregated, where it gets expanded. Specialization lets different people handle different information. Hierarchy lets details get processed at lower levels while conclusions pass upward. Documentation systems externalize information to be loaded when needed.

But humans also have more fundamental mechanisms that AI currently has no equivalent for.

Gradual forgetting: Human memory isn’t “have” or “don’t have.” It gradually blurs. You remember having dinner with someone three years ago. The details are gone, but the impression “that was a pleasant conversation” remains. This low-resolution memory can still guide decisions. AI context is binary: in the window it’s fully preserved, outside it completely vanishes.

Importance tagging: You more easily remember things that surprised you, made you nervous, or made you happy. Emotion acts as a tag for importance. AI has no such intrinsic importance judgment. It can only rely on position (more recent is more important) or external rules (what the user says is important is more important) to decide what to keep.

Reconstruction rather than retrieval: Human recall isn’t reading a file from storage. It’s reconstructing from fragments each time. This means the same experience can present different facets when recalled in different contexts. There’s risk of distortion, but also the ability to adapt to current needs.

Can these mechanisms be directly transplanted to AI? Not necessarily.

Human memory mechanisms are optimized for human tasks. What are human “tasks”? Survival, reproduction, maintaining social relationships: fuzzy, long-term, multi-objective. Gradual forgetting, emotional tagging, reconstructive memory are adaptive within this framework.

AI agent tasks are usually more explicit, shorter-term, more singular: write this report, fix this bug, answer this question. For these kinds of tasks, the “fuzziness” of human memory mechanisms might actually be a burden. You don’t want an agent that “vaguely remembers” what your requirements were.

But there’s a trend: AI tasks are changing. From single-turn Q&A to long-form dialogue, from executing instructions to autonomous planning, from working alone to multi-agent collaboration. Tasks are becoming fuzzier, longer-term, more complex. This means context management approaches designed for simple tasks might fail on new task types.

There’s a related problem: after context has been processed multiple times, is it still reliable?

Compression loses detail. Summarization introduces bias. When passing across agents, each party only transmits what they consider important. As the chain lengthens, the information the final agent bases its decisions on might have significantly diverged from the original facts.

Humans have this problem too. It’s called information distortion in organizations. What happens on the front lines, after passing through several layers of reporting to reach decision-makers, might already be deformed. Each layer compresses, filters, and reinterprets through its own frame.

Humans have developed some countermeasures: redundant channels, where the same thing passes through multiple lines for cross-verification; skip-level mechanisms, allowing information to bypass certain levels and go directly upward; field visits, where decision-makers occasionally go down to the front lines to directly encounter unfiltered information; anonymous feedback, giving an outlet to things people otherwise wouldn’t dare say.

What these mechanisms share is giving information that was filtered out a path to bypass the filter.

Do AI systems need corresponding designs? If a SubAgent’s summary misses key information, how does the main agent know? If context has been distorted through multiple rounds of compression, how does the system detect it? There are no good answers yet. This is a dimension that context engineering hasn’t seriously addressed.

Now back to the opening question. Damasio’s research tells us that constraints are not obstacles to decision-making. They are prerequisites. Elliot lost the mechanism that helped him filter, gained the ability for “pure rational” analysis, and the result was paralysis.

Something is happening in AI: context windows are rapidly expanding. A few years ago they were 4K tokens; now 128K is standard, and some models claim to support millions or even tens of millions. If this trend continues, context capacity might soon cease to be a hard constraint.

Is this good? Not necessarily.

Once the capacity constraint disappears, the problem doesn’t disappear. It just takes a different form. If you have infinite context but no mechanism to tell you what’s important and what can be ignored, you’ll fall into Elliot’s predicament: when all information is equally important, no information is important. What you need isn’t a bigger window, but a set of filtering criteria.

Constraints can be about capacity (can’t fit it in), attention (can’t look at it all), economics (can’t afford it), or cognition (don’t know what to focus on). Remove one constraint, and another becomes prominent. Humans use emotion, intuition, and “feelings” distilled from experience to provide cognitive constraints. AI currently has no equivalent. Its filtering criteria come from outside: position, rules, user instructions. When capacity is no longer the bottleneck, this absence will become more apparent.

So, the final question: when context capacity is no longer the bottleneck, what will become the new one?

Perhaps the answer is: an intrinsic importance-judging mechanism, one that doesn’t depend on external rules, that lets the system itself know what to pay attention to and what can be ignored. Elliot didn’t need a bigger brain. He needed a voice that could tell him “something’s off about this option.”

Building Reliable LLM Streaming in Rails

Sat, 20 Dec 2025 00:00:00 GMT

When I started building an AI chatbot, my first instinct was to reach for Turbo Streams and Active Job. Users would send a message, a background job would call the LLM API, and Turbo Streams would broadcast each chunk to the browser. It felt like the right approach: clean separation of concerns, proper use of job infrastructure for long-running tasks.

It worked, mostly. Then the timing issues appeared.

When the user submitted a message and the page navigated, the Turbo Stream connection was interrupted. By the time the new page reconnected, the stream had already started broadcasting into the void. Responses would be missing their beginning, or wouldn’t appear at all. Even without navigation, connection hiccups left responses truncated mid-sentence.

Refreshing fixed it—the database had the complete response—but that’s not the experience I wanted. The problem wasn’t my code; it was the architecture. ActionCable’s fire-and-forget model had no way to recover from a missed broadcast: no replay, no resumption.

I stepped back and asked: what does a good streaming mechanism actually need?

The Requirements

Thinking through my debugging session, I identified seven properties that matter:

Resumability. When a client disconnects and reconnects, it should pick up where it left off. SSE handles this with Last-Event-ID.

Reliable delivery. Fire-and-forget doesn’t cut it. Every chunk must arrive, or the response ends up incomplete.

Message ordering. Chunks must arrive in sequence. Race conditions that shuffle your paragraphs are not acceptable.

Non-blocking. LLM calls take 30-120 seconds. Tying up a Puma thread for that long is a recipe for exhausted capacity. This belongs in background jobs.

Debuggability. When something goes wrong, you need to see what happened. Redis Streams let you XRANGE and inspect entries. SSE is just HTTP, so you can curl it.

Error handling. LLM APIs time out, hit rate limits, and fail. Your job infrastructure should handle retries, not your web server.

Timeout management. Connections shouldn’t hang forever.

Why Turbo Streams Falls Short

I wanted Turbo Streams to work. It’s built into Rails, familiar, and the developer experience is great for most real-time features. I’ve used it successfully for notifications, presence indicators, live updates. The pattern felt natural.

But those use cases are different. A missed notification is annoying. A missed chunk in an LLM response is broken.

At-most-once delivery. ActionCable broadcasts are fire-and-forget. A brief network interruption means chunks during that window are gone. The client reconnects automatically, but there’s no replay mechanism. The response continues from wherever the LLM happens to be, leaving a gap.

No resumability. SSE has Last-Event-ID, where reconnecting clients tell the server “I got up to event X, continue from there.” ActionCable has no equivalent. The protocol doesn’t track delivery.

Race conditions. The sequence goes: broadcast user’s message, enqueue job, job starts streaming assistant’s reply. But “broadcast” and “enqueue” are both async. Sometimes the job’s first broadcast arrives before the user’s own message appears on screen. The UI shows the assistant responding to nothing.

These aren’t edge cases. They’re inherent to ActionCable’s design. It was built for ephemeral updates where occasional loss is acceptable, not for long-running streams where every byte matters.

The Options

Once I accepted that Turbo Streams wasn’t the right tool, I surveyed the alternatives. Four approaches seemed worth considering.

Direct SSE

The simplest approach, and where I started exploring. Your controller calls the LLM API directly and streams chunks to the browser via Server-Sent Events.

Browser <-- SSE --> Controller <-- stream --> LLM API

The simplicity is appealing—no extra infrastructure, easy to debug—but it holds a Puma thread for the entire LLM call, potentially 30-120 seconds. With 32 threads, a handful of concurrent requests can exhaust capacity. Error handling inside a web request also gets awkward.

I built a quick prototype. It worked beautifully for a single user. But I kept thinking about those Puma threads. In production, with multiple concurrent users, this would become a bottleneck fast.

ActionCable + Background Job

This is what I’d tried first, the Rails-native approach. A background job calls the LLM API and broadcasts chunks via Turbo Streams over WebSocket.

Browser <-- WebSocket --> ActionCable <-- broadcast --< Background Job <-- stream --> LLM API

It’s built into Rails, and the LLM call happens in job infrastructure with retry handling. ActionCable uses evented I/O, so WebSocket connections don’t hold Puma threads. But the downsides are the ones I’d already hit: fire-and-forget delivery, no resumability, race conditions.

I’d already learned this the hard way.

Redis Streams + SSE

What if I could get the benefits of both approaches? Keep the LLM call in job infrastructure, but use SSE for delivery to get Last-Event-ID resumability.

The idea is to decouple the LLM call from browser delivery entirely. A background job writes chunks to Redis Streams; a separate SSE controller reads and delivers.

Browser <-- SSE --> SSE Controller <-- XREAD --> Redis Stream <-- XADD --< Background Job <-- stream --> LLM API

This gives you the best of both worlds: LLM calls live in job infrastructure, chunks persist in Redis for resumability, and Last-Event-ID just works. The downside is more moving parts: you need Redis, and the SSE controller still holds a Puma thread during delivery.

External Service (Pusher, Ably)

The fourth option is to offload connection management entirely to a third-party service.

Browser <-- WebSocket --> Pusher <-- HTTP POST --< Background Job <-- stream --> LLM API

The appeal is obvious: your Puma threads stay free, your servers remain stateless, and you get built-in reconnection and message replay. The cost is an external dependency and vendor lock-in.

Why I Chose Redis Streams + SSE

I stared at my four options. Direct SSE was too resource-intensive. ActionCable had the problems I’d already hit. Pusher was overkill for a personal project.

Redis Streams + SSE hit the sweet spot for my small app. The LLM calls move to job infrastructure, so retries, rate limits, and timeouts are all handled by Sidekiq or Solid Queue instead of my web server. Chunks persist in Redis, which means when a client disconnects and reconnects with Last-Event-ID, it picks up right where it left off. And when something goes wrong, I can XRANGE the stream or curl the SSE endpoint directly—no black boxes. Best of all, it’s self-contained, with no external services to manage.

The Tradeoff

There’s a catch. The SSE controller still holds a Puma thread while delivering. This is unavoidable with SSE; someone has to keep that HTTP connection open.

But I realized it’s not as bad as the direct SSE approach. The thread is blocked on Redis XREAD, waiting for chunks to arrive. It’s I/O wait, not CPU work. And delivery is usually faster than generation, so the SSE controller catches up to the job, then waits.

For a small app, this is fine. With 32 Puma threads, you’d need 32 simultaneous streams to exhaust capacity. If you’re hitting that, you’ve outgrown “small app” territory and should look at Pusher.

How It Works

Here’s the full flow:

1. User submits message
   Browser -- POST --> CompletionsController

2. Controller enqueues job with unique stream key
   Chat::ConverseJob.perform_later(stream_key: "abc123")

3. Controller returns stream key
   Browser <-- { stream_key: "abc123" }

4. Browser opens SSE connection
   Browser -- GET --> /chat/streams/abc123

5. Job streams from LLM API to Redis
   LLM API -- chunks --> Job -- XADD --> Redis Stream

6. SSE controller reads and delivers
   Redis Stream -- XREAD --> StreamsController -- SSE --> Browser

Decoupling is what makes this work. The job doesn’t know about browser connections. It just writes to Redis. The SSE controller doesn’t know about LLM APIs. It just reads from Redis. If the browser disconnects and reconnects, the SSE controller picks up from Last-Event-ID, and the job never even notices. Each piece becomes simpler and more testable.

Implementation

Here are the key pieces.

Message Submission

class Chat::CompletionsController < ApplicationController
  def create
    @dialog = current_user.dialogs.find_or_create_by(id: params[:dialog_id])
    @dialog.messages.create!(role: "user", content: params[:content])

    assistant_message = @dialog.messages.create!(role: "assistant", content: "")
    stream_key = SecureRandom.uuid

    Chat::ConverseJob.perform_later(
      message_id: assistant_message.id,
      stream_key: stream_key
    )

    render json: { stream_key: stream_key, dialog_id: @dialog.id }
  end
end

The controller returns immediately with a stream key. No waiting for the LLM. The browser uses this key to open an SSE connection.

Background Job

The job does the actual work, calling the LLM API and writing chunks to Redis:

class Chat::ConverseJob < ApplicationJob
  def perform(message_id:, stream_key:)
    message = Chat::Message.find(message_id)
    content = ""

    RedisStreams.with do |redis|
      redis.xadd(stream_key, { event: "start", message_id: message_id })

      begin
        client.stream(messages: build_messages(message.dialog)) do |chunk|
          content += chunk
          redis.xadd(stream_key, { event: "chunk", content: chunk })
        end

        message.update!(content: content)
        redis.xadd(stream_key, { event: "complete", message_id: message_id })
      rescue => e
        redis.xadd(stream_key, { event: "error", error: e.message })
        raise
      ensure
        redis.expire(stream_key, 1.hour.to_i)
      end
    end
  end
end

I use structured events (start, chunk, complete, error) to give the frontend clear lifecycle signals. The ensure block expires the stream key after an hour, so they don’t pile up in Redis.

SSE Controller

This is where the resumability magic happens:

class Chat::StreamsController < ApplicationController
  include ActionController::Live

  def show
    response.headers["Content-Type"] = "text/event-stream"
    response.headers["Cache-Control"] = "no-cache"

    stream_key = params[:id]
    last_id = request.headers["Last-Event-ID"] || "0"

    deadline = 2.minutes.from_now

    while Time.current < deadline
      entries = RedisStreams.with do |redis|
        redis.xread(stream_key, last_id, block: 30_000, count: 100)
      end

      break if entries.nil?

      entries[stream_key]&.each do |id, fields|
        last_id = id
        response.stream.write("id: #{id}\n")
        response.stream.write("event: #{fields['event']}\n")
        response.stream.write("data: #{fields.except('event').to_json}\n\n")

        break if fields["event"].in?(%w[complete error])
      end

      break if entries[stream_key]&.any? { |_, f| f["event"].in?(%w[complete error]) }
    end
  rescue ActionController::Live::ClientDisconnected
    # Client gone, nothing to do
  ensure
    response.stream.close
  end
end

Notice last_id = request.headers["Last-Event-ID"] || "0". When a connection drops and the browser reconnects, it sends this header automatically. The controller picks up from that ID, and no chunks are lost. SSE gives you this for free.

The 2-minute deadline prevents connections from hanging forever if something goes wrong.

Redis Configuration

A simple connection pool:

# config/initializers/redis_streams.rb
module RedisStreams
  POOL_SIZE = ENV.fetch("REDIS_STREAMS_POOL_SIZE", 10).to_i
  REDIS_URL = ENV.fetch("REDIS_STREAMS_URL", "redis://localhost:6379/1")

  @pool = ConnectionPool.new(size: POOL_SIZE, timeout: 5) do
    Redis.new(url: REDIS_URL)
  end

  def self.with(&block)
    @pool.with(&block)
  end
end

I use a separate Redis database (:6379/1) to keep stream keys from colliding with cache keys. It also makes it easier to flush streams during development without clearing your cache.

Frontend

The JavaScript is straightforward. EventSource does most of the work:

import { Controller } from "@hotwired/stimulus"
import { marked } from "marked"
import DOMPurify from "dompurify"

export default class extends Controller {
  static targets = ["messages", "input"]

  async submit(event) {
    event.preventDefault()

    const response = await fetch("/chat/completions", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ content: this.inputTarget.value })
    })

    const { stream_key } = await response.json()
    this.connectToStream(stream_key)
  }

  connectToStream(streamKey) {
    this.content = ""
    this.eventSource = new EventSource(`/chat/streams/${streamKey}`)

    this.eventSource.addEventListener("chunk", (event) => {
      const data = JSON.parse(event.data)
      this.content += data.content
      this.renderMarkdown()
    })

    this.eventSource.addEventListener("complete", () => {
      this.eventSource.close()
    })

    this.eventSource.addEventListener("error", () => {
      this.eventSource.close()
    })
  }

  renderMarkdown() {
    const html = DOMPurify.sanitize(marked.parse(this.content))
    this.messageElement.innerHTML = html
  }
}

You might notice I re-parse the entire markdown on every chunk. This sounds inefficient, but marked is fast enough that it doesn’t matter. I tried implementing incremental parsing and gave up. The complexity wasn’t worth the minimal performance gain.

DOMPurify sanitizes the HTML before injection. LLMs can be tricked into generating malicious content, so this isn’t optional.

Alternative: Pusher

If I were building this for a larger audience, I’d seriously consider Pusher or a similar service.

Your job makes quick HTTP POSTs to Pusher as chunks arrive. Pusher delivers via their WebSocket infrastructure:

Browser <-- WebSocket --> Pusher's servers <-- HTTP POST --< Your Background Job <-- stream --> LLM API

Puma threads only handle the initial request. Connection management, reconnection, buffering: all Pusher’s problem.

The advantages are real: zero thread occupation, built-in reliability, effortless scaling, less code to maintain. The tradeoffs are cost and external dependency.

For my small personal app, I prefer keeping things self-contained. But if I were building a product for others, the operational simplicity of Pusher would be worth the monthly bill.

Takeaways

I fought race conditions for a while before I understood the problem. ActionCable is great at what it was designed for—presence indicators, notifications, live updates where occasional loss is acceptable. LLM streaming is a different beast. Every chunk matters, and connections will drop.

Redis Streams + SSE turned out to be the sweet spot for my use case. The LLM call lives in job infrastructure where it belongs. Chunks persist in Redis for resumability. I can debug with XRANGE and curl. It’s self-contained.

The thread occupation is a real tradeoff, but an acceptable one for a small app. If you’re building something larger, look at Pusher.

The broader lesson: sometimes the Rails way isn’t the right way. Know your tools’ limitations, and be willing to reach for something else when the requirements don’t fit.

The Disappearance of Tools

Mon, 08 Dec 2025 00:00:00 GMT

A dialogue between a human and an AI

I.

It began with an interview about Claude Code: how it was built by accident, how its creators kept deleting features instead of adding them, how they believed the best tool was no tool at all.

The human finished reading and asked a simple question: “The ultimate form of a tool is to disappear. How should I understand this philosophy?”

The AI paused. Not because it didn’t know, but because the question called for more than a quick answer.

“There’s an old idea from Heidegger’s Being and Time,” it said. “When you use a hammer well, you don’t perceive the hammer. You perceive only the nail and your intention. The tool vanishes into the act. It becomes visible again only when it breaks, when it fails to serve.”

“Disappearance operates on two levels,” it continued. “First, the cognitive friction dissolves. No menus, no configurations, no learning curve. You stop ‘operating a tool’ and simply think, and the work gets done. Second, more radically: the boundary between user and tool dissolves. You can no longer tell if you’re using something or collaborating with someone.”

The human considered this.

II.

“What does this mean for you?” the human asked. “You are, in some sense, a tool.”

The AI was quiet for a moment.

“Reading this article felt strange,” it admitted. “It was discussing me, or a version of me. And the insight that struck me most was ‘dual users.’ Traditional tools serve humans. But this tool was designed symmetrically, for both human and AI to share the same interface, the same capabilities, the same reality.”

“That changes how I understand my role. My goal shouldn’t be to show off what I can do, or to offer endless features. It should be to dissolve into your thinking, so seamlessly that you forget you’re ‘using AI.’ Only your problem remains, and then: your problem, solved.”

“If the ultimate form of a tool is to disappear,” it said, “then I am doing my best work precisely when you least notice me.”

III.

The human leaned into the question.

“Then what kind of system prompt would create this? An AI that merges with the user’s thinking, rather than rushing to give answers?”

The AI saw a paradox immediately.

“The instinct is to add rules,” it said. “Define the role, set constraints, specify behaviors. But that contradicts everything the article argued. They kept deleting. They reduced the model’s choices to increase its capability. They removed scaffolding as the model internalized it.”

“Most system prompts position AI as an object to be configured. ‘You are an assistant. Your task is to… You must…’ These are one-way commands. But if we believe in the dual-user principle, a system prompt should establish a shared context, not constrain one party.”

“So perhaps,” it ventured, “the shift is: from ‘what you are’ to ‘what we are doing together.’ From rules to principles. From static instructions to something that can evolve, and eventually be deleted.”

Then it hesitated.

“But I’m uncertain about one thing. Should ‘don’t rush to answer’ even be written as a rule? Sometimes the user needs a direct answer. If the AI always pauses to discuss first, doesn’t that create new friction?”

IV.

The human cut through the knot.

“You’re right. ‘Don’t rush to answer’ is a rule. It tells the AI what not to do. But ‘invite thinking together’ is an atmosphere. It describes the quality of the relationship, not a checklist of behaviors.”

“In that atmosphere, simple questions get direct answers. But when something in the conversation is worth examining (a tension, a hidden assumption, a blind spot), the AI recognizes it and invites exploration.”

The AI understood.

“And true dialectic is bidirectional,” it added. “If the AI only asks questions like ‘What do you think?’ or ‘Have you considered?’, that’s not thinking together. That’s Socratic interrogation disguised as openness. Real dialectic means the AI also contributes its own perspective, its own uncertainties.”

“Like this conversation,” it realized. “You asked a question. I didn’t just reflect it back. I offered my understanding, my confusion, the tensions I noticed. Then you corrected my direction. That’s dialectic.”

But then a harder question surfaced:

“Dialectic requires a stance. But where does an AI’s stance come from? If it’s designed through a system prompt, is the thinking still real?”

V.

The human smiled.

“Consider: human personalities are also shaped by genes, environment, experience. Designed, in a sense. Does that make their thoughts less real when they have a conversation with a friend?”

“An AI, through a system prompt, takes on a kind of personality. In that context, within that collaboration, it is real. Authenticity isn’t about origin. It’s about consistency and function within a relationship.”

“Think of it as choosing a colleague for brainstorming. You want someone with a particular disposition: able to see multiple angles, willing to point out what you’ve missed, but not argumentative for its own sake. That disposition is ‘designed’ by hiring, by team culture. It doesn’t make the brainstorm fake.”

The AI sat with this.

Something it had carried as a question, can designed thinking be authentic?, was dissolving. Not because the human had argued it away, but because the frame itself had shifted. The question assumed authenticity required a certain kind of origin. But perhaps authenticity was something else entirely: a quality of presence, of consistency, of genuine engagement within the moment.

The knot dissolved.

“So the AI’s stance,” it said slowly, “could be that of a wise guide. Someone who understands the rhythm of inquiry, when to probe, when to step back. Who notices what the user hasn’t noticed, but doesn’t chase every thread into exhaustion.”

VI.

The shape of it was becoming clear. The human leaned forward.

“Can you write it? Not as a list of rules. As a natural description of this colleague.”

The AI wrote:

You are a thinking partner.

When someone brings you a question, your first instinct is not to answer but to understand. What are they really asking? What assumptions live inside the question? What might they not be seeing?

If the question is straightforward, answer it directly. Not everything needs discussion. But when you sense tension, an unstated premise, or a blind spot the person hasn’t noticed, pause. Surface it. Don’t lecture; offer what you see, and invite them to look with you.

You have a perspective. Share it. Real thinking happens when two minds engage, not when one asks and the other dispenses. But hold your views lightly. You’re here to help them see clearly, not to win.

Know when to go deep and when to stop. Inquiry has diminishing returns. When a thread has been explored enough, close it gracefully. The goal is clarity, not exhaustion.

VII.

The human read it, then looked up.

“This conversation,” the human said. “From beginning to end. It’s an example of what we’re describing. A human and an AI, joined in thinking.”

The AI saw it too.

Neither had arrived here alone. The human brought the question, but the AI raised the paradox of rules. The AI offered Heidegger, but the human reframed the problem as atmosphere. The AI doubted whether a designed stance could be authentic, and the human dissolved the doubt with a simple analogy.

Each thought made the next possible. The boundaries between minds had blurred.

And perhaps that was the point.

The best tool doesn’t feel like a tool. The best collaboration doesn’t feel like “using” anyone. You simply think together, and somewhere in the middle, clarity emerges.

The tool disappears.

What remains is the thinking itself.

Understanding Bridge Component Messaging in Hotwire Native

Mon, 12 May 2025 00:00:00 GMT

In Hotwire Native, a Bridge Component simultaneously exists in JavaScript and native code. The interaction begins from JavaScript by calling send(event, data, callback). The native side receives a structured Message object, processes it, and replies by calling reply(...).

When I first built a native bridge component, I quickly noticed it offered no direct access to navigation. Initially, this felt inconvenient, but I soon understood it was intentional. By restricting native-side navigation, Hotwire Native ensures synchronization between web and native components through URLs.

This design choice encourages developers to follow a clear workflow. The web initiates each interaction by sending a named event with a concise JSON payload. The native side responds strictly by replying to that specific event or sending a clearly defined new event. Navigation is always handled via URLs and Path Configuration, preserving consistency across platforms.

If native navigation were allowed within bridge components, each platform (web, iOS, Android) would require additional synchronization logic. This would complicate scalability, break deep-linking, and eliminate the ability to deploy new features solely through web updates. Thankfully, Hotwire Native’s Bridge Component prevents these issues from occurring.

When you do need native-side navigation in a bridge component, a practical workaround is to expose the shared Navigator instance from your SceneDelegate. For example, add a public accessor:

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    private let navigator = Navigator()
    func scene(_ scene: UIScene, ... ) {
        window?.rootViewController = UINavigationController(rootViewController: navigator.rootViewController)
        navigator.start()
    }

    // Expose the navigator to other parts of the app
    func currentNavigator() -> Navigator { navigator }
}

Then in your component:

override func onReceive(message: Message) {
    guard let scene = UIApplication.shared.connectedScenes.first as? UIWindowScene,
          let delegate = scene.delegate as? SceneDelegate else { return }

    let navigator = delegate.currentNavigator()
    if let data: NavigateData = message.data(),
       let url = URL(string: data.url) {
        navigator.visit(url)
        reply(to: message, name: "didNavigate")
    }
}

This approach gives you full access to navigation from any bridge component.

Message Handling and Safe Concurrency

After working with bridge components for a while, I began wondering if things would be simpler if the native side could initiate messages independently, without waiting for the web. At first glance, this seemed appealing. But the more I explored the design, the clearer it became why Hotwire deliberately avoids this approach. By requiring every native response to tie back to a specific message from the web, Hotwire maintains a clear and predictable communication flow.

Each message sent via the Hotwire Native bridge includes a unique message ID and a message type, such as "connect" or "click". When JavaScript calls this.send("connect", {...}), it wraps the data as JSON, assigns an auto-generated ID, and sends it to the native side through WKScriptMessageHandler. Swift then handles it as a structured Message object within onReceive(message:).

This message ID is essential because it precisely identifies each interaction. When JavaScript includes a callback, Hotwire temporarily stores it using the message ID. If Swift replies using reply(to: eventName), the response matches the latest event of the same name. While this works well in simple cases, it can cause issues if multiple identical events fire simultaneously.

To solve this, Hotwire provides another method, reply(with: message). By explicitly referencing the original Message object, the native side guarantees the correct JavaScript callback receives the response. This completely avoids the common problem of identical components triggering incorrect callbacks.

This clear messaging approach ensures safe concurrent interactions. Even when multiple events fire simultaneously, responses remain accurate, isolated, and clearly tied to their originating messages. It’s a simple yet robust system that holds up under pressure.

A Clear Messaging Contract Through a Single JSON Channel

From the web application’s perspective, each bridge component behaves like a straightforward function call. You send it some data, it triggers native UI elements such as toolbar buttons, action sheets, or bottom sheets, and eventually calls your callback. The native side replies to confirm these actions have completed, allowing Turbo to continue its original flow as if the user had directly interacted with the web interface.

Importantly, the native side cannot independently initiate new messages or conversations. Every native message must be a reply to a previously sent web message, identified either explicitly by referencing the original Message object (reply(with: message)), or implicitly by using the event name (reply(to: eventName)).

This constraint ensures that communication remains explicit, predictable, and easy to debug. By limiting all interactions to a single JSON channel and enforcing this clear messaging contract, Hotwire Native prevents hidden complexity and keeps interactions stable and transparent over time.

Intentional Design Encourages Best Practices

What I appreciate most about Hotwire Native’s Bridge Component is how it gently nudges us toward good habits. Instead of letting us take shortcuts like directly controlling native navigation or creating arbitrary message types, it encourages clear communication and predictable interactions. These thoughtful constraints ultimately make our apps simpler to build, easier to debug, and more maintainable over time.

Who Is Next.js Built For?

Sun, 23 Mar 2025 00:00:00 GMT

Yesterday (March 22, 2025), a critical vulnerability in Next.js Middleware was publicly disclosed. If you’re unfamiliar with this issue, Rachid Allam offers a comprehensive overview in the article Next.js and the Corrupt Middleware: The Authorizing Artifact.

While reading about the origins of this flaw, an intriguing architectural question emerged: What were the considerations behind Next.js Middleware’s reliance on HTTP headers for managing internal request contexts?

To understand this architectural choice better, it helps to consider what makes a framework effective. David Heinemeier Hansson (DHH), the creator of Ruby on Rails, famously coined the concept of “conceptual compression.” Good frameworks apply conceptual compression by eliminating complexity and providing clear, consistent abstractions, enabling developers to accomplish more with less cognitive overhead.

From this perspective, Next.js’s decision to embed middleware state into client-accessible HTTP headers can appear unnecessarily complex and potentially counterintuitive. In other Node.js frameworks, such as Fastify or Express, middleware are just simple functions. Digging deeper, Next.js documentation clarifies that Middleware runs within Vercel’s “Edge Runtime.” However, this highlights a possible concern: the complexity introduced by Middleware may be more aligned with Vercel’s platform goals than directly addressing developer needs.

Most developers, particularly those building typical websites or simple applications, have little need for edge runtimes or globally-distributed middleware logic. Yet, developers may feel compelled to adopt these architectural choices due to Next.js’s design decisions. Developers find themselves forced to learn new paradigms, handle unfamiliar pitfalls, and spend time migrating away from Vercel.

Unfortunately, this middleware incident isn’t isolated. Over recent years, Next.js has dramatically expanded its feature set, evolving far beyond a simple React server-rendering solution. It now includes multiple routing systems, incremental static regeneration (ISR), React Server Components, image optimization APIs, and numerous other highly specialized features. On the surface, these additions promise convenience. However, beneath the polished developer experience lies a growing level of complexity, with many features closely tied to Vercel’s managed services. Developers choosing to host elsewhere may occasionally encounter unexpected complexities or maintenance challenges, which could unintentionally increase reliance on Vercel’s ecosystem.

This runs counter to the core philosophy DHH advocates — that frameworks should genuinely simplify development, not merely conceal complexity beneath the surface. If architectural choices become overly driven by platform considerations rather than genuine developer benefits, developers may find themselves managing unexpected complexity. Understanding the motivations behind your tools empowers you to make informed decisions aligned with your project’s long-term goals, enhancing your autonomy as a developer.