Learning that the user never reads the manual

There's a humbling moment every system builder faces. It’s when you realize the carefully written manual, the thoughtful UI labels, and the logical process flows are artifacts of your own intent, not a map of user behavior. This isn't a new phenomenon. Research from experts like Jakob Nielsen at the Nielsen Norman Group has shown for decades that users scan, they don't read. They are goal-oriented, not process-oriented, and this truth should be the starting point for our architecture.

For years, I've seen systems designed for an obedient user fail upon contact with a real one. The challenge isn't to force users to follow our prescribed path. The real architectural work is to build systems that embrace their heuristic, shortcut-driven reality.

From Brittle Rules to Resilient Intent

A purely deterministic system is brittle. It expects structured data, sequential actions, and predictable inputs. When a user pastes an unformatted block of text into a field designed for a postal code, the system breaks. This isn't a user error; it's an architectural one. We built a system that understands rules, not intent.

The modern data and AI stack gives us new tools to bridge this gap. Instead of just validating input against a rigid schema, we can now build an interpretation layer. For example, a small, local LLM can act as a "structuring agent" at the edge. It takes the user's messy, free-text input and attempts to translate it into the clean, validated JSON object our deterministic backend API requires. The goal is to make the system resilient by moving the burden of translation from the human to the machine.

The Hybrid Pattern: Agents and Pipelines

The most durable pattern I've found is a hybrid of agentic flexibility and deterministic safety. The agentic system acts as a smart front door, interpreting the "what" of a user's request. The deterministic system is the secure factory in the back, reliably executing the "how."

An LLM agent can parse a vague user query like, "show me the European sales figures from last quarter." It can infer the date range, identify the correct entities, and formulate a structured query. But that query should never execute directly. Instead, it's handed to a deterministic validation pipeline. This pipeline checks permissions, enforces query limits, validates parameters, and ensures the operation is safe and efficient. The agent proposes; the deterministic pipeline disposes.

This separation of concerns is critical. It allows us to leverage the power of LLMs to understand ambiguity without exposing our core systems to the risks of their probabilistic nature. The deterministic guardrails are the boring, unglamorous part of the architecture that keeps the system from failing at 3am.

The Unseen Costs of Ambiguity

This hybrid approach is powerful, but it is not free. The hype often ignores the trade-offs. An agentic layer introduces latency; a call to an LLM is orders of magnitude slower than a simple validation check. It adds significant operational cost, both in compute and in the complexity of monitoring a non-deterministic component.

Observability becomes much harder. When a deterministic pipeline fails, a stack trace usually points to the cause. When an agent misinterprets a user's intent, the failure is semantic and much harder to debug. This architecture demands a deep investment in logging the agent's reasoning, tracing its outputs, and creating clear fallback paths. To be clear, this is not the only valid design philosophy. In high-stakes domains like medical devices or industrial controls, the correct choice is often radical simplification, as championed by thinkers like Don Norman in his book The Design of Everyday Things, where ambiguity is designed out entirely. For most enterprise systems, however, we must manage it.

Observability: The Manual Users Write for Us

If we accept that we cannot force users to read our manual, we must commit to reading theirs. Their manual is written every day in the logs, traces, and metrics our systems generate. Deep observability is not a feature; it is the central feedback loop for evolving an architecture that serves real-world behavior.

By analyzing how users actually navigate the system, where they get stuck, and what "wrong" inputs they constantly try, we uncover the truth. This data shows us where our mental model of the system diverged from theirs. It highlights which ad-hoc workarounds are becoming permanent workflows. This is the information that should drive architectural refinement—not a static design document, but a living record of use and misuse.

Key Takeaways: Build for how users actually behave, not how you wish they would. Use a hybrid architecture where a flexible agentic layer interprets intent, but critical actions are enforced by deterministic pipelines. Acknowledge the high cost of this approach in latency and complexity. Finally, invest heavily in observability; the usage data your system generates is the only manual that accurately reflects reality.