Originally published at: https://www.auklabs.io

You've been building with an agentic tool for two weeks. Something breaks. You read the code and realize the agent made a decision you never asked it to make — and you have no idea when it made it or why. You make a change. Something else breaks. You make another change. Three changes later you're reading code you didn't write, trying to understand decisions you didn't make, and you've completely lost the thread of what you were originally trying to do. This is exactly what using an agent was supposed to help you avoid.

That's not a bug. That's the gap.

One of our biggest fears about agentic systems is that we won't know what they're doing. For me, the more interesting question is what leads to the decisions they're making — especially when tasks are underspecified or context is missing.

Agents Are Precise

Agentic coding tools are remarkably precise at executing what you ask them to do. Give an agent a goal and it can perform every task required to achieve that goal without asking for permission. That’s the feature, that’s the intent — agents assume that you’ve fully specified what you want, and where you haven’t, they make assumptions based on what they know. But that feature is also where things go quietly wrong.

Agents don’t drift because they are careless; they drift because they are filling in gaps. Gaps in our specification, gaps in our instructions, gaps between what we said and what we meant. Agents fill in those gaps with inference and then move on. They don’t record what they inferred, and they don’t flag what was missing. They just execute. By the time we’ve realized that something has gone wrong, we’ve lost the thread of context that would help us answer What and Why.

The industry is starting to recognize this as a systemic issue. Engineers at Thoughtworks and elsewhere have started calling this "cognitive debt" — the erosion of shared understanding that accumulates when AI-generated code embeds design decisions invisibly in the output. It is the hidden cost of moving fast.

This article is about a different approach: making gaps between intent and implementation visible before they compound, and making assumptions explicit while you’re still in a position to correct them.

An Unknown Unknown, Close Up

Software development is, at its core, a process of discovery. When a human engineer works on a complex system, they carry deep, implicit knowledge about the system’s architecture, constraints, and unwritten rules. They know when to pause, when to ask a question, and when a decision is too consequential to make unilaterally.

I’ve been frustrated by the gap between what I intend to build and what agentic tools actually produce — not because the tools are imprecise, but because I am. The assumptions that I make, the details that I leave out, and the instructions that I fail to give are the ones that cost me. What follows is a story about a gap I didn't know existed, surfaced by a methodology I’m building to find exactly these types of gaps.

Despite using a combination of Test-Driven Design, Spec-Driven Design, and a prompt that attempts to minimally implement each unit of work (which I call a "Slice") in the pipeline, I received the following message at the end of one of those Slices:

system.md referenced in the Slice 3 definition does not exist in the config. The configured artifacts cover the system-contract role. If system.md is added as a formal artifact in a future slice, ArtifactRole and FOREIGN_RULES in src/artifacts.ts must be extended.

A follow-up analysis revealed something worth paying attention to. The original configuration schema had been defined with five keys. Later, the file system.md was added as a core artifact to provide guidance on what must remain true across all future work. The canonical execution prompt, also written separately, never mentioned it either. This meant that the reference document system.md was defined, but not mentioned in the configuration file that described the core artifacts, the PRD, or the canonical execution prompt.

Three documents. One gap. No record of a decision to exclude it.

The absence wasn’t deliberate. There was just no recorded rationale for leaving it out. It was simply missing. The reference document clearly stated: "The agent reads system.md for what it must respect." The agent was executing correctly against an incomplete specification, and that was fine — until it wasn’t.

I didn't know what I didn’t know. But the guardrails that I put in place for execution helped me identify the problem and reason about what went wrong. After observing that gap in execution, I ran a review, and the agent was able to explain why I didn’t know what I didn’t know.

Here is the exact output the execution loop produced when it encountered the gap — not a crash, not a silent failure, but a structured explanation of what was missing and why it mattered:

## Why system.md Is Not in raes.config.yaml

The config was designed in an execution slice (2026-04-19, Gap 1 in raes-reference.md Section 11). That slice defined 5 keys: `build_intent`, `next_slice`, `durable_decisions`, `execution_guidance`, `validation`.

`system.md` was **not included at that time**. The reference doc notes that `prd-ux-review.md` is *intentionally* absent from the config (Section 9, explicit). For `system.md`, there is no such explicit exclusion — its absence appears to be an oversight from when the schema was first defined, not a design decision.

Evidence supporting this interpretation:
- raes-reference.md Section 3 describes system.md as a core truth artifact alongside PRD and decisions.md
- raes-reference.md line 67: "The agent reads `system.md` for what it must respect."
- Yet the canonical prompt (Section 7, lines 193-260) never mentions system.md, nor does it include a config key for it
- The execution loop therefore has no directed path to the constraint surface system.md is meant to provide

Stopping at the Right Moment

The methodology that surfaced that gap is called RAES — Reusable AI Execution System. I want to be clear about what it is and what it isn't, because the name invites assumptions that aren't accurate.

RAES is not an agent framework. It doesn't orchestrate tool calls or manage autonomous planning loops. It doesn't make the agent smarter or more capable. What it does is simpler and, I'd argue, more useful: it structures the moments where human judgment is required during execution, and it makes sure those moments leave a record.

The core idea is that AI-assisted development has two distinct failure modes. The first is execution failure — the agent does something wrong. That's visible. Tests fail, code breaks, the problem surfaces quickly. The second is judgment failure — the agent does something reasonable that isn't what you intended, based on an assumption you didn't know it was making. That failure is invisible until it compounds.

RAES is built for the second failure mode. It does this through three mechanisms:

1. A structured execution loop that separates two fundamentally different types of work — implementation and review — and applies different rules to each. Forcing planning work through an implementation loop produces bad outputs. Most tools don't make this distinction.

2. A decision record with a promotion rule. When a decision is made during execution that will affect all future work, it gets recorded in two places: the rationale goes into decisions.md, and the resulting constraint gets promoted into system.md — the file whose absence started this whole story. It looks like this:

Decision (2026-04-19): system.md added as core truth artifact. Constraint promoted to system.md: "All future slices must validate against the constraint surface defined here." Rationale: prevents silent exclusion of cross-cutting constraints from execution prompts.

One artifact answers why. The other answers what must remain true. They reference each other. Future work reads the constraint without having to excavate the rationale.

3. Explicit gap surfacing. When the execution loop encounters something missing, conflicting, or ambiguous, it stops and flags it rather than inferring its way through. That's what happened with system.md. The loop didn't guess. It named the gap, identified the downstream consequence, and handed it back to me.

You might ask: Why can't I just do this with a well-written AGENTS.md or .cursorrules file?

The difference is that those files are static. They describe how the agent should behave, but they do not record what the agent decided or why. They are rules, not a record. decisions.md is the dynamic equivalent: it is updated during execution, not before it. The distinction matters because the gap that caused the system.md problem was not a missing rule — it was a missing record of a decision that was never made explicitly.

That discipline is harder to build than it sounds. The default behavior of every agentic tool I've used is to keep moving. RAES is built around the assumption that stopping at the right moment is more valuable than executing at speed.

What We Don’t Know We Don’t Know – Yet

The system.md gap wasn't the last one I found. It was just the first one I could explain clearly.

That's the nature of unknown unknowns. You don't find them by being more careful or more thorough. You find them by building systems that are designed to look for them — and that say something when they do.

RAES is early. The tooling is incomplete. raes-execute, the CLI that will automate what I'm currently doing with a carefully constructed prompt, doesn't exist yet. The methodology is being used to build itself, which is either a sign that it works or a sign that I have an unusually high tolerance for recursive problems. Probably both.

What I know is this: the discipline of making assumptions explicit, recording decisions as they happen, and surfacing gaps before they compound has changed how I work with agentic tools. Not because it slows things down — it doesn't, not meaningfully — but because it changes what I trust. I trust the output more when I can see the reasoning behind it. I trust the system more when I know it will stop and tell me what it doesn't know.

That's not a feature any of the tools I compared against are optimizing for. They're optimizing for speed, for autonomy, for the feeling of progress. RAES optimizes for something quieter: the confidence that what got built is actually what you meant to build.

If that gap resonates with you — if you've felt the specific frustration of knowing something went wrong but not knowing when the assumption that caused it was made — I'd like to hear about it. The repository is at github.com/aabdullah-bos/raes. It's open, it's MIT licensed, and it's actively being developed.

If you want to see the methodology in practice, start with docs/raes-reference.md — it's the document the methodology used to build itself.

If you're building something in this space, thinking about execution discipline for AI-assisted development, or just have a story about a gap you didn't know you didn't know — reach out. The methodology gets better when more people are finding the things they didn't know they were missing.

The unknown unknowns are still out there. The point is to build systems that find them before they find you.