01 · The problem
Why your agent keeps getting it wrong.
Agents don’t ask. They guess. A new engineer who can’t tell whether a change
is right will ask someone. Your agent won’t. It reads your documentation literally,
works at machine speed, holds your credentials, and has exactly one way to find out
whether it succeeded: whatever your repository can prove.
So most of what gets reported as “the model keeps getting this wrong” is
neither a model problem nor a prompting problem. The agent simply has no way
to check itself. In one repository we audited, there was plenty for the agent
to read — 75 out of 100 — and almost nothing to check against:
14 out of 100. Better prompts do not move that. Neither does a better model.
The ceiling is set by what your repo can verify, not by what it can explain.
A lock you can’t open isn’t the same as a lock you can’t inspect.
Which is the useful part. The fix is ordinary engineering with a schedule attached:
tests on the paths that matter, checks wired into CI, the conventions your team already
follows written down once. Waiting for the next model release will not help. It has
never seen your codebase.