DEV Community: Aquil Abdullah

AI Agents and the Things We Didn’t Know We Didn’t Know

Aquil Abdullah — Wed, 06 May 2026 02:38:22 +0000

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.

Vibe Coding Needs Telemetry

Aquil Abdullah — Thu, 26 Mar 2026 20:00:19 +0000

Originally published at: https://www.aquilabdullah.com/your-post-url

I recently noticed something strange in the backend telemetry of a code base that I was working on.

A single API request was triggering more than twenty database calls.

The code looked perfectly reasonable, but the telemetry told a very different story.

A Simple Vibe Coding Exercise

Imagine you're building a simple profile endpoint.

You ask your AI assistant to create something that returns:

user information
the sports they participate in
posts they've written
events they're attending

A reasonable implementation might look like this:

user = get_user(user_id)
sports = get_user_sports(user_id)
posts = get_user_posts(user_id)
events = get_user_events(user_id)

return {
    "user": user,
    "sports": sports,
    "posts": posts,
    "events": events
}

At first glance, this looks great.

Each function is small.

Each responsibility is clear.

The code is readable and easy to test.

From the perspective of local code correctness, this is good code.

But from the perspective of system behavior, something subtle may have just happened.

The N+1 Query Problem

If each of those helper functions hits the database, this endpoint just turned into multiple queries.

Instead of one database call, we now have several.

This pattern is known as the N+1 query problem.

It usually appears when you:

run 1 query to fetch a list
then run N additional queries to fetch related data

For example:

get_users()

for each user:
    get_posts(user)

If you load 10 users, that becomes 11 queries.

If you load 100 users, that becomes 101 queries.

Each individual query is fast.

But together they create unnecessary load and extra round trips.

What started as clean, modular code quietly turns into a query fan-out pattern.

When Telemetry Tells a Different Story

It took me a minute to realize what I was looking at.

The endpoint didn’t look suspicious, but the telemetry did.

During a single request, I saw repeated database calls like this:

21:15:40 GET /sports
21:15:40 GET /users
21:15:40 GET /event_rsvps
21:15:41 GET /sports
21:15:41 GET /users
21:15:41 GET /event_rsvps

The same resources being requested over and over again.

The code looked clean.

But the system was doing far more work than I expected.

Why This Happens More With AI

AI coding tools are very good at generating locally correct code.

They optimize for:

readability
modularity
clear abstractions

But they don’t automatically reason about:

query fan-out
database round trips
system-level performance

So you end up with code that looks right, but behaves differently than you expect at runtime.

Fixing the Query Fan-Out

Once you notice an N+1 pattern, the solution is usually to move more work into the database.

Common approaches include:

JOIN queries
database views
materialized views
RPC functions

In this case, I used a database RPC function.

Instead of making multiple application-level calls, the database assembles the full result in a single operation.

Conceptually:

Before:
API → many database calls

After:
API → single RPC → database assembles result

This reduces round trips and makes the endpoint behavior predictable.

The Observability Mindset

What struck me most about this bug was that the code itself looked perfectly reasonable.

Nothing obviously inefficient.

But telemetry told a different story.

That’s the shift that comes with AI-assisted development.

We can generate systems faster than ever.

But speed makes it easier to miss how those systems behave under the hood.

Telemetry gives you visibility into:

how many queries an endpoint triggers
how requests flow through your system
where load is actually happening

Without it, you're relying on what the code suggests.

With it, you can see what the system is actually doing.

Before and After

Before the fix:

Request → ~20 database queries

After moving the logic into an RPC function:

Request → 1 database call

Same endpoint.

Very different behavior.

Closing Thought

AI can generate endpoints quickly.

Telemetry tells you what those endpoints are actually doing.

Co-programming with GPT-4o: A Love Story Gone Recursive

Aquil Abdullah — Fri, 16 May 2025 23:33:36 +0000

Before we get started, let’s get one thing straight: this article breaks no new ground!

If you search Google, Bing, DuckDuckGo, or Perplexity for the phrase “Co-programming with GPT-4o,” you’ll find plenty of tales of woe about using GPT-4o as your pair programming partner.

So why did I do it?

Well, besides being a glutton for punishment, I asked GPT-4o,

“What is the best OpenAI model for co-programming?”

And it replied:

“[GPT-4o] 🔥 Overall best for co-programming.”

So there you have it! ChatGPT-4o told me it was the “Best of the best of the best…Sir!”

We Hit It Off Swell!

Everything started out great. I had an idea, and GPT-4o chatted me up. It told me how amazing my idea was and promised to help turn it into an app.

It provided me with a skeleton for the codebase and even gave me the exact statements I’d need to get started. We waxed philosophically about the merits of npm and yarn, and why it chose npm for this project.

When I mentioned that I wanted to use TypeScript instead of JavaScript, GPT-4o kindly converted the code and pointed out which type definitions I needed to install.

At this point, we were totally vibing.

I was poo-pooing everyone who had claimed GPT-4o couldn’t code.

YOU DOWN WITH GPT?

YEAH YOU KNOW ME.

Code? What Code?

A few days later, I came back to my prototype to make some frontend changes. GPT-4o walked me through the edits, asked if I wanted it to generate a new file, and I said yes.

I first suspected something was off when I noticed the new file was 50 lines shorter. When I ran the app, the styling was completely different.

I asked what went wrong. GPT-4o told me it had lost context. I offered to upload the current version, and it obliged — we were back on track.

There were a few more moments like this — context loss during refactoring, odd choices I wouldn’t have made — but I wrote them off as the cost of doing business.

I was still down with GPT.

But was GPT-4o still down with me?

The Ides of March or Et tu GPT-4o

The final blow came when I was refactoring some logging logic. My good friend GPT-4o suggested we DRY up the code. I was like:

“OK, GPT-4o, I see you modularizing my code and making reusable components!”

It took this:

const logDir = process.env.LOG_PATH || path.join(__dirname, '../../logs');
const logPath = path.join(logDir, 'conversations.jsonl');

And converted them into the function:

function getLogFilePath(): string {
  let logDir = process.env.LOG_DIR || getLogFileDir(); // 🚨 infinite recursion!
  let logPath = Path2D.join(logDir, 'conversations.jsonl');
  return logPath;
}

Yep, you read that right: Path2D.join(...).

I don’t know if that was hallucination or performance art, but either way, it wasn’t helpful. (And yes, I think it meant path.join(...).)

When I pointed out the infinite recursion, GPT-4o thanked me and recommended a fix.

Still, I figured it was time to get to a stopping point and try a different model.

So I asked GPT-4o to complete one last task: finish DRYing up a few more parts of the code.

I uploaded the current file. Asked for a clean rewrite. GPT-4o gave me broken output.

I tried again. And again. And again.

Five uploads later, I finally figured out the issue: a newline character was being mishandled during patching.

When I flagged it, GPT-4o jumped in and said:

You’re spot on — the newline string is easy to break in patching logic because:

'\n' (Python-escaped newline) looks correct in code but often renders as 'n' or literal text if mishandled

This is a common gotcha in regex-based manipulation when we don’t parse the code structure semantically

I appreciated the honesty. But I also wanted working code.

Conclusion

There are things GPT-4o does really well. And to be fair, the model has already improved since this experiment. It was helpful with scaffolding, converting JavaScript to TypeScript, and even philosophical debates about dependency managers.

But co-programming isn’t just about vibes. It’s about trust, context, and precision — especially when you’re iterating on real-world code.

If you decide to vibe-code with GPT-4o, make sure you’ve got version control, a good debugger, and a willingness to triple-check newline characters.

As for whether GPT-4o is still “🔥 Overall best for co-programming”?

Let’s just say… it's still under review.