AI Has Made Me a Text Parser. And I'm Terrible at That.

Jun 2, 2026 · ai · agents · claude

An AI-generated decision summary for a Stripe subscription build: 18 decisions grouped into Foundations, Product model and other areas for a human to review.

I ask Claude to write a feature spec. It produces ten pages in roughly a minute. My agent swarm is ready to start implementing, but only after I approve the spec. So I sit down to read it.

That validation takes me two hours.

I have written before about being the bottleneck in my own agent frameworks because I cannot spec fast enough. This is one specific reason I had not named yet: I cannot validate fast enough either. The output arrives instantly. My ability to understand it does not.

Humans Are Not Text Parsers

I was implementing a Stripe payment integration. The agent produced a full spec: the happy path, declined card handling, webhook events... Ten pages. All correct, all necessary, and completely impossible to hold in my head at once while reading.

A markdown spec file open in an editor: ten pages of dense text, the kind you cannot hold in your head while reading.

Markdown is the right format for agents. But I am not an agent.

I asked the agent to regenerate few flows as a Mermaid (opens in a new tab) diagram. I understood the whole structure before I finished scrolling.

The same payment flow as a Mermaid sequence diagram: registration, trial expiry and purchase across frontend, backend, subscription service and Stripe.

Same content. Ten times faster comprehension.

The diagram is not smarter. I am just much less stupid when looking at it.

That is not a small difference. That is the difference between being a bottleneck and not being one.

The Missing ViewModel

I also tried switching Markdown to HTML. Seven pages of HTML is almost as heavy as ten pages of Markdown. Format helps a little. But the real fix is surfacing. AI needs to decide what I need to see, not just how to format everything it produced.

In software development, you do not dump the entire database onto the end user. There are layers. The data model is one thing. The UI focuses the user's attention on what actually matters, and all the background data stays under the hood.

I was not building my AI workflows that way. I was accepting direct database dumps.

The same principle applies here. Raw content stay as the source that agents read. For the human, you render a different view. One source, different views for different readers. The agent sees structured context. The human sees a decision.

One thing I had to get clear: filtering for the human does not mean deleting information. The agents still need the full context, all the reasoning, the rejected options, why certain decisions were made. If that disappears, they repeat the same mistakes. The architecture is one source with everything in it, and from that source you render different views. The agent view is the full structured context. The human view is filtered and visual. Same source. Different lenses.

Every developer knows MVVM. The Model holds the data. The ViewModel transforms it for the View. You never expose the raw Model directly to the UI.

Agent frameworks have the Model (.md raw content). What is missing is the ViewModel, the layer that transforms the same source into something each consumer can actually use. I started building one into my own workflows because the alternative was reading walls of text indefinitely.

I have made two concrete changes to how I work with agents.

The first is in the instruction file. When I define what an agent should produce, I also define how it should present it to me. Not just "write a feature spec" but "write a feature spec, and generate a human-facing decision view: key decisions, options, trade-offs, recommendations, and diagrams where structure matters." The agent should know how to present information, not just what to produce.

The second is in how decisions get surfaced during a conversation. I now instruct agents to present decisions one at a time, not as a list. For each one: "describe the situation, research what options are relevant to our context, filter out what is not, present what remains, and give a recommendation". That instruction lives in the agent's system prompt or project-level instruction file, the same place I define everything else about how the agent should work. Even when there are ten decisions to make, they arrive one by one. Each is easy to absorb and act on. That change alone has made my conversations with agents significantly faster.

Claude Code presenting a single "Checkout style" decision with selectable options and a recommendation, rather than a wall of choices.

Use the AskUserQuestion tool to let Claude Code surface a decision with clear, selectable options.

Why This Actually Matters

If I do not understand what I am approving, I am not validating it. I am just letting errors pass through.

Critical decisions get buried on page seven. The agent continues in the wrong direction. I find out much later, when something is already built, already merged, already sent.

That same feature spec workflow looks different now. The agent still produces ten pages. But what lands in front of me is a communication view: the key decisions at the top, a flow diagram where there are dependencies, and the full detail available when I need to go deeper. The same MVVM pattern we use to build products for end users, applied to how my agents communicate with me.

A communication view: the Stripe subscription build summarised as 18 grouped decisions, each with a recommended default to confirm or override.

Validation takes ten minutes instead of an hour.

AI has already scaled my output. Now I need to scale my ability to understand what I am approving.

Same agent. Same output volume. Different communication layer.