The Parts of Your Job an Agent Can't See

An agent working on your codebase has the code, the tests, the tickets, and whatever documentation exists. That sounds like most of the job. It is missing a category of input that determines whether the work is any good, and the gap isn't closing on its own — because the missing things were never written down.

What isn't in the repository

Why the system is shaped this way. The awkward abstraction that exists because of a migration that half-finished in 2023. The service boundary drawn around a team that no longer exists. The code shows the shape; the reason lives in people's memory, and the reason is what tells you whether the shape is still load-bearing.

What's about to change. The team knows a rewrite is planned for next quarter, so nobody is investing in this module. An agent optimizing it thoroughly is doing careful work that gets deleted.

What the requester actually wants. The ticket says one thing. The conversation where they described the problem said something adjacent, and the real constraint surfaced in an aside. The ticket is a lossy summary of a conversation, and the loss is systematic — the parts hardest to articulate are the parts that get dropped.

What's politically or organizationally possible. A technically correct change that requires another team to move, when that team is mid-crisis, is not a correct change this quarter.

What's already been tried. Someone attempted this two years ago and it went badly. There's no record. The only artifact is that a senior engineer looks uneasy when it's proposed.

How much this actually matters. Whether it's worth doing well, doing quickly, or doing at all is a judgment about business context that exists in nobody's tracked artifacts.

Why "just write it down" doesn't close the gap

The standard response is to document more, and it helps at the margin. It doesn't close the gap, for three structural reasons.

Most of it is not known to be relevant until it is. Nobody documents "we don't invest in this module" as a fact; it's a shared understanding that surfaces when someone proposes investing.

The volume is enormous and the value is sparse. Writing down everything that might matter produces a corpus where the important thing is indistinguishable from the noise, which is the retrieval problem again.

Some of it is unwritable. "This customer is difficult and the account is fragile" is real, load-bearing, and not going into a document anyone will circulate.

⚠️ This isn't an argument against documentation. It's an argument against expecting documentation to make tacit context legible, because the tacit part is defined by resisting that.

What this means practically

Feed context deliberately, per task. The highest-leverage thing you do when working with an agent is supplying the two or three pieces of unwritten context that bear on this specific task. "This module is being replaced, so keep the change minimal." "The constraint is that the finance team needs the old field name for another quarter." A single sentence of that is worth more than any amount of prompt tuning.

Treat agent output as proposals, not decisions. Work produced without the missing context is a competent answer to a question that may have been slightly wrong. Reviewing it is not a formality — it's where the missing context gets applied.

Notice which context you keep supplying. ✅ A piece of context you find yourself giving every time is one that should be written down, and now you know it's load-bearing because it keeps mattering. This is a much better documentation strategy than trying to write everything in advance.

Value the people who hold it. The engineer who knows why things are the way they are is holding an input nothing else supplies. That's worth more as the rest of the work gets cheaper, not less.

🔍 A way to see the gap

Take a recent piece of work you did well and ask: what did I know that isn't in any artifact, and what would have been different without it?

The answer is usually two or three things, and they're usually the difference between the work being right and being merely plausible. That set is the gap — for now, and for any agent working from the same artifacts you'd have handed a new colleague.

The takeaway

An agent sees the code and the tickets. It doesn't see the history, the plans, the politics, the abandoned attempts, or what the requester meant rather than wrote. Supply that deliberately for each task, review output as proposals rather than answers, and write down the pieces you notice yourself repeating. The gap narrows where you close it on purpose — and the part that stays open is a large share of what your judgment is actually for.