Capturing Intent

Before the summer I wrote about comprehension debt and how we need to stay on top of what AI is creating under our supervision - or non-supervision. Whoever merges a request should be able to explain what it does.

In recent weeks I suppose I’d like to refine that view a little. Or rather extend.
Let’s revisit technical debt and comprehension debt.

1. Technical Debt: Conscious decision to not implement something because it’s out of scope, adds too much complexity or can be added later.
2. Comprehension Debt: Accept code to be added to the codebase without really understanding what it does or if that feature is really needed. AI convinced us somehow it is.

With AI agents it becomes easier to just have the agent pay down the technical debt. Point the agent to the issue (which hopefully provides all the context necessary to implement it) and off you go.
Comprehension debt can be paid down to some degree as well: The code describes what the software does. So we can ask an agent to analyse the code, maybe go through some logs and describe what is happening under the hood. But does it actually implement what the author was asking for?

That’s where we enter intent debt: What was the actual user/author intent and context behind the code? Sure, an AI agent can hallucinate a possible intent - but it is not possible to decipher the intent from looking at the code.

When you work with agents, please keep in mind to capture the intent and make it an artefact of your work. Elaborate issues and PRs in your GitHub repos, or (IMHO even better) something like OpenSpec to capture the intent in a more structured way. I’d even suggest to use the grill-me skill to make sure the OpenSpec artefact is captured sufficiently.