We Track Changes and Decisions. We Don’t Track Intent – and AI Makes It Worse.
A deeper look at the missing layer in modern systems
The Problem You Don’t Notice – Until You Do
Most systems don’t fail loudly. They don’t crash or burn or take down everything at once. Instead, they drift. Something small breaks. A constraint is violated. A user notices before the system does.
You open the logs expecting answers. And the logs are there. Plenty of them. Requests came in, retries happened, downstream services responded, and eventually things succeeded. From a purely observational standpoint, the system behaved exactly as expected.
And yet, something is wrong.
What We Actually Preserve
We are very good at preserving certain kinds of knowledge. Version control systems capture exactly what changed. Architecture Decision Records explain why a particular direction was chosen. Together, they give us a fairly complete picture of how a system evolved over time.
But there is a category of knowledge that slips through the cracks. It is not recorded in commits. It is not formalized in design documents. It lives briefly during development and then disappears.
That category is intent.
A Simple Example That Isn’t So Simple
Consider a payment system. A user submits a payment request. The system attempts to process it, encounters a timeout, and retries. Eventually, the payment succeeds.
- request_received
- paymentattemptfailed
- retry
- payment_success
Looking at this sequence, nothing appears unusual. This is what distributed systems are supposed to do. Failures happen, retries compensate, and eventual success is achieved.
But then a user reports that they were charged twice.
At that moment, the logs stop being helpful. They describe what happened, but they do not explain why the outcome is unacceptable. The system followed its execution path correctly. The problem lies elsewhere.
The Missing Constraint
The real issue is that the system never encoded a simple rule: a payment must be processed exactly once. That rule existed during design. It may have been discussed in meetings or written in a temporary document. But it was never made part of the system in a durable way.
Without that constraint, the system cannot recognize its own failure. It only knows how to execute, not how to judge.
We Reconstruct What We Should Have Recorded
When debugging, engineers often reconstruct intent from behavior. They read logs, trace execution paths, and try to infer what the system was supposed to do. This works most of the time, but it is fundamentally reactive.
It assumes that intent can always be recovered after the fact. In reality, that reconstruction is incomplete and often wrong.
A Different Way to Think About Systems
Instead of treating intent as something implicit, we can make it explicit. Not as documentation, but as a first-class artifact.
Imagine that every meaningful change carries a small piece of structured context describing what the system is trying to achieve.
- Intent:
- Goal: Process payment
- Constraint: Must not charge more than once
- Tradeoff: Favor correctness over latency
This does not replace code. It complements it. It captures reasoning that would otherwise disappear.
What Changes When Intent Exists
With intent available, debugging shifts from observation to validation. Instead of asking what happened, you ask whether the outcome aligns with the declared goal.
In the payment example, the duplicate charge becomes immediately visible as a violation. The logs still provide detail, but they are no longer the primary tool for understanding correctness.
Architecture With Intent
Intent Layer n ↓ n Application Logic n ↓ n Observability Systems
This model separates purpose from execution. The application performs work, and observability records behavior, but intent defines what success actually means.
Why This Matters More Now
As systems grow in complexity, the gap between behavior and understanding widens. Teams become larger, ownership becomes fragmented, and context becomes harder to maintain.
At the same time, automation accelerates development. Changes happen faster, but the reasoning behind them becomes more ephemeral. AI-assisted contributions amplify this effect—code is generated, modified, and iterated on rapidly, often without preserving the original intent behind those decisions.
Without a way to capture that intent, systems begin to accumulate invisible assumptions, making it increasingly difficult to reason about correctness over time.
The Real Cost
The absence of intent leads to an over-reliance on logs and metrics. Engineers try to compensate by increasing observability, but this often creates noise rather than clarity. As a result, they spend hours digging through logs, reconstructing context that was never captured in the first place.
More data does not lead to better understanding. Without intent, it simply increases cognitive load—turning debugging into a time-consuming exercise instead of a focused investigation.
Conclusion
Modern systems are built on strong foundations of observability and version control. But they are missing a critical layer that connects behavior to purpose.
By capturing intent explicitly, we give systems a way to reason about correctness, not just execution. We reduce ambiguity, improve debugging, and make systems easier to evolve.
Because in the end, knowing what happened is not enough. You also need to know what was supposed to happen.
