The Key Word in my AI Prompts

I’ve been using AI for over two years, progressing from clever auto-completion through vibe coding to agentic engineering. Recently I iterated for a couple of weeks over a prototype application. The biggest problems came down to a single word, a term I’m found myself using more than any other over the last few weeks. And it’s not exclusive to a single project. It’s a term that’s been used across coding work, research work, everything.

That word is intent. It’s a term I’ve seen repeatedly through this year in research papers, blog posts and videos about AI this year. It’s detailed in a technical paper by Margaret-Ann Storey “ From Technical Debt to Cognitive and Intent Debt: Rethinking Software Health in the Age of AI”, which looks like it was earlier covered in her blog. I came to it from Addy Osmani’s blog post. But I had also seen other YouTube videos talking about intent.

When I see a topic being repeated, I pay attention. When it’s not fashion, there’s a good reason, there’s an important problem people are independently identifying.

Content Overload

The root of cognitive debt comes from content overload - lots of code being generated and lots of documentation being generated. Certain models are very keen to generate documentation to explain what they’re doing. And at the speed models write or change code, the documentation quickly becomes outdated, contradictory, or partially duplicated. Because the models generate code so quickly, the instinct is to continue generating new code, and at best to skim-read the documentation produced. I have found myself regularly asking the model to review the documentation and archive what’s outdated, but even so, there is content overload.

And the problems I’ve encountered come down to two areas.

Firstly, the model takes the “happy path”. It effectively says, “I did this, I remember what I did, I don’t need to check.” This can mean content (both code and documentation) focuses on what’s most recent, not the full and proper functionality.

Secondly, the focus is insufficient, and the key is something I said earlier: the models generate documentation to explain what they did.

5 Ws and H

Many, many years ago I did a managerial course. One of the concepts covered in the course was “5 Ws and H”, a framework relevant to problem-solving and project management. The 5 Ws are who, what, where, why, and when. The H is how.

The problem with cognitive and intent debt, and the problem with AI-generated documentation is it’s very good at covering what the code is, where it is, when it’s triggered, maybe who it’s triggered by, and how it’s called. But it’s not good at why it’s there.

At best, it tries to reverse engineer the “why” based on “what” the code does.

Why and Intent

But the “why” is the crucial part. It’s the information that feeds into your decision-making process, the intent that determines why you choose a particular implementation.

More importantly, the intent is what feeds into future decisions. Without understanding the intent, the model cannot choose the right implementation. And if the intent is not captured in the documentation, a decision that looks wrong may get changed later. We’ve all seen this in past, where code that looks wrong or unnecessary requires a comment to explain why it exists. In the human coding era, that was sufficient for the “why” on detail, and the senior engineers had the big picture that gave the “why” for architectural choices for an application, and they were the ones who turned requirements into implementation designs or pushed back on customers because what they say the want will conflict with the intent of the system.

Multiple Intents

And this is the other key: there is never just one intent; there are multiple intents in play at different times. For a given user story, one intent may override another. In a different part of the application, a different intent may take priority.

I hit this particular problem recently with a change. I identified a problem with the code and explained a gap in the working. But the implementation changed pre-existing functionality, assuming the new requirement superseded the earlier on. Sometimes that’s right, sometimes it’s wrong. Intent is what feeds into the decision-making process for when a feature augments or replaces functionality.

This can also work the same in reverse with conflicting intents. If an agent’s instructions just say “ensure all existing tests still pass”, I an envisage a scenario where you might get dead or wrong code paths just to ensure tests still pass. With cognitive overload, the problem may get missed.

Intent and Decision-Making

With simple features or fixes, telling the model what to do is sufficient. But when things are more complex, the right implementation is driven by an understanding and awareness of the intents of the system. Otherwise you get something that appears to tick the boxes but is not fit for purpose. This is why I have found myself regularly just telling the model not only what I want to achieve, but also the intent behind it.

I think there’s a key reason this is happening more and more this year, it’s because of the move to agentic engineering.

Plans are built together with a model, with detailed discussions on what is needed and getting a shared understanding. But the discussion gets distilled into the plan. The plan often focuses on the “what”, the “how”, and the “where”. Agents can often write plans with specific code blocks to add, specific location to update. That’s fine in the “happy path” where everything just works. If not, the factors feeding into decision-making may get lost because the agent is just working from the plan.

When it comes to the documentation, again the agent works from the closest source - the code. The documentation gets generated from the code, which has been generated from the plan, which is a distillation of the initial discussion. The intent can get diluted out by the process.

Historically pull requests might also have been where intent was reinforced. But if the pull requests get generated by agents, they get built through code and tests, not intent. if the drive is “does the code do what it should”, the intent doesn’t disseminate across the whole team.

The Need for Speed

Margaret-Ann Storey’s paper doesn’t answer a question I’d be interested to know: why did the problem of cognitive debt arise in that situation?

The example is of a student team and a wall hit at week eight. But is the problem because AI allowed the team to get further down the road than teams in the era of human coding? So did they hit a problem that historical teams never hit because their applications didn’t get as big, so an absence of documentation did not become a problem? Or did the problem occur because the quality of documentation was worse than historical teams, because they were seduced by the opportunity of quicker development?

The answers do not dilute the importance of the issue. The “need for speed” is undoubtedly causing a problem with cognitive debt. It’s whether the availability of speed created a problem that was lurking before, but not identified because the teams did not get as far down the road.

Summary

That “need for speed” is a definite risk for increased code slop, degraded or absent documentation, tests that pass but are not fit for purpose, for cognitive and intent debt.

Intent and effective sharing of intent is key to giving agents the key information to make good decisions. And intent is something I think is regularly buried subconsciously at the back of developers’ minds, assumed knowledge that requires conscious thought to share.